feat: add token usage, response timing, and block properties

- Add TokenUsage and ResponseTiming models to MessageBlock
- Populate usage from all provider engines (streaming and non-streaming)
- Track completion timing in CompletionHandler
- Add web_search_mode to MessageBlock and persist in DB
- Add MessageBlockPropertiesDialog for viewing block metadata
- ResponseTiming: add request_sent_at, first_token_at; TTFT, generation duration
- completion_handler: capture request_sent_at, first_token_at for streaming
- DB: persist usage_json, timing_json on message_blocks (migration 005)
- Add usage_utils with provider-specific extractors; refactor all engines
- Add Properties context menu item for message blocks (Alt+Enter)

Author: AAClause

basilisk/completion_handler.py

@@ -11,6 +11,7 @@
 import re
 import threading
 import time
+from datetime import datetime
 from typing import TYPE_CHECKING, Any, Callable, Optional
 
 import wx
@@ -153,6 +154,7 @@ def _handle_completion(self, engine: BaseEngine, **kwargs: dict[str, Any]):
 			engine: The engine to use for completion
 			kwargs: The keyword arguments for the completion request
 		"""
+		started_at = datetime.now()
 		try:
 			play_sound("progress", loop=True)
 			response = engine.completion(**kwargs)
@@ -161,6 +163,11 @@ def _handle_completion(self, engine: BaseEngine, **kwargs: dict[str, Any]):
 			wx.CallAfter(self._handle_error, str(e))
 			return
 
+		# Request is fully sent when completion() returns (streaming: we have the stream)
+		request_sent_at = (
+			datetime.now() if kwargs.get("stream", False) else None
+		)
+
 		handle_func = (
 			self._handle_streaming_completion
 			if kwargs.get("stream", False)
@@ -169,6 +176,8 @@ def _handle_completion(self, engine: BaseEngine, **kwargs: dict[str, Any]):
 		self._last_completed_block = None
 		kwargs["engine"] = engine
 		kwargs["response"] = response
+		kwargs["started_at"] = started_at
+		kwargs["request_sent_at"] = request_sent_at
 		try:
 			success = handle_func(**kwargs)
 		except Exception as e:
@@ -270,7 +279,12 @@ def _handle_streaming_completion(
 		if self.on_stream_start:
 			wx.CallAfter(self.on_stream_start, new_block, system_message)
 
-		for chunk in engine.completion_response_with_stream(response):
+		first_token_at: datetime | None = None
+		for chunk in engine.completion_response_with_stream(
+			response, new_block=new_block
+		):
+			if first_token_at is None:
+				first_token_at = datetime.now()
 			if self._stop_completion or global_vars.app_should_exit:
 				logger.debug("Stopping completion")
 				return False
@@ -282,6 +296,17 @@ def _handle_streaming_completion(
 			wx.CallAfter(self._handle_stream_buffer, f"\n{END_REASONING}\n\n")
 		# Parse legacy ```think...``` format into reasoning + content
 		self._split_reasoning_from_content(new_block)
+		started_at = kwargs.get("started_at")
+		request_sent_at = kwargs.get("request_sent_at")
+		if started_at is not None:
+			from basilisk.conversation.conversation_model import ResponseTiming
+
+			new_block.timing = ResponseTiming(
+				started_at=started_at,
+				request_sent_at=request_sent_at,
+				first_token_at=first_token_at,
+				finished_at=datetime.now(),
+			)
 		if self.on_stream_finish:
 			wx.CallAfter(self.on_stream_finish, new_block)
 		return True
@@ -306,9 +331,16 @@ def _handle_non_streaming_completion(
 		Returns:
 			True if non-streaming completion was handled successfully, False if stopped
 		"""
+		from basilisk.conversation.conversation_model import ResponseTiming
+
 		completed_block = engine.completion_response_without_stream(
 			response=response, new_block=new_block, **kwargs
 		)
+		started_at = kwargs.get("started_at")
+		if started_at is not None:
+			completed_block.timing = ResponseTiming(
+				started_at=started_at, finished_at=datetime.now()
+			)
 
 		# Notify that non-streaming completion has finished
 		if self.on_non_stream_finish:

basilisk/conversation/conversation_model.py

@@ -27,6 +27,81 @@
 )
 
 
+class TokenUsage(BaseModel):
+	"""Token consumption for a completion request.
+
+	Normalized across providers. All fields optional except where noted.
+	"""
+
+	input_tokens: int = 0
+	output_tokens: int = 0
+	reasoning_tokens: int | None = None
+	cached_input_tokens: int | None = None
+	total_tokens: int | None = None
+
+	@property
+	def effective_total(self) -> int:
+		"""Total tokens (computed if not provided)."""
+		if self.total_tokens is not None:
+			return self.total_tokens
+		return self.input_tokens + self.output_tokens
+
+
+class ResponseTiming(BaseModel):
+	"""Timing for a completion request."""
+
+	started_at: datetime | None = None
+	request_sent_at: datetime | None = None
+	first_token_at: datetime | None = None
+	finished_at: datetime | None = None
+
+	@property
+	def duration_seconds(self) -> float | None:
+		"""Total duration in seconds (start to last token), or None if incomplete."""
+		if self.started_at is None or self.finished_at is None:
+			return None
+		return (self.finished_at - self.started_at).total_seconds()
+
+	@property
+	def time_to_send_request_seconds(self) -> float | None:
+		"""Time from start until request fully sent. None if request_sent_at unknown."""
+		if (
+			self.started_at is None
+			or self.request_sent_at is None
+			or self.request_sent_at < self.started_at
+		):
+			return None
+		return (self.request_sent_at - self.started_at).total_seconds()
+
+	@property
+	def time_to_first_token_seconds(self) -> float | None:
+		"""Time from request sent to first token received (TTFT). None if unknown."""
+		# Use request_sent_at when available, else started_at for backward compat
+		from_ts = (
+			self.request_sent_at
+			if self.request_sent_at is not None
+			else self.started_at
+		)
+		if (
+			from_ts is None
+			or self.first_token_at is None
+			or self.first_token_at < from_ts
+		):
+			return None
+		return (self.first_token_at - from_ts).total_seconds()
+
+	@property
+	def generation_duration_seconds(self) -> float | None:
+		"""Time from first token to last token (excludes TTFT). None if first_token_at unknown."""
+		if (
+			self.first_token_at is None
+			or self.finished_at is None
+			or self.finished_at < self.first_token_at
+		):
+			return None
+		return (self.finished_at - self.first_token_at).total_seconds()
+
+
 class MessageRoleEnum(enum.StrEnum):
 	"""Enumeration of the roles that a message can have in a conversation."""
 
@@ -150,12 +225,15 @@ class MessageBlock(BaseModel):
 	reasoning_budget_tokens: int | None = Field(default=None)
 	reasoning_effort: str | None = Field(default=None)
 	reasoning_adaptive: bool = Field(default=False)
+	web_search_mode: bool = Field(default=False)
 	output_modality: str = Field(default="text")
 	audio_voice: str = Field(default="alloy")
 	audio_format: str = Field(default="wav")
 	created_at: datetime = Field(default_factory=datetime.now)
 	updated_at: datetime = Field(default_factory=datetime.now)
 	db_id: int | None = Field(default=None, exclude=True)
+	usage: TokenUsage | None = Field(default=None)
+	timing: ResponseTiming | None = Field(default=None)
 
 	@field_validator("response", mode="after")
 	@classmethod

basilisk/conversation/database/manager.py

@@ -23,7 +23,9 @@
 	Message,
 	MessageBlock,
 	MessageRoleEnum,
+	ResponseTiming,
 	SystemMessage,
+	TokenUsage,
 )
 from basilisk.custom_types import PydanticOrderedSet
 from basilisk.provider_ai_model import AIModelInfo
@@ -385,6 +387,13 @@ def _create_db_block(
 		csp_id: int | None,
 	) -> DBMessageBlock:
 		"""Create and flush a DBMessageBlock, updating block.db_id."""
+		usage_json = None
+		if block.usage:
+			usage_json = block.usage.model_dump_json()
+		timing_json = None
+		if block.timing:
+			timing_json = block.timing.model_dump_json()
+
 		db_block = DBMessageBlock(
 			conversation_id=conv_id,
 			position=block_index,
@@ -395,6 +404,9 @@ def _create_db_block(
 			max_tokens=block.max_tokens,
 			top_p=block.top_p,
 			stream=block.stream,
+			web_search_mode=getattr(block, "web_search_mode", False),
+			usage_json=usage_json,
+			timing_json=timing_json,
 			created_at=block.created_at,
 			updated_at=block.updated_at,
 		)
@@ -667,6 +679,61 @@ def get_conversation_count(self, search: str | None = None) -> int:
 			query = self._apply_search_filter(query, search)
 			return session.execute(query).scalar_one()
 
+	def _load_block_from_db(
+		self, db_block: DBMessageBlock
+	) -> MessageBlock | None:
+		"""Build a MessageBlock from a DBMessageBlock. Returns None if block has no request."""
+		request_msg = None
+		response_msg = None
+		for db_msg in db_block.messages:
+			if db_msg.role == "user":
+				request_msg = self._load_message(db_msg)
+			elif db_msg.role == "assistant":
+				response_msg = self._load_message(db_msg)
+
+		if request_msg is None:
+			log.warning("Block %d has no request, skipping", db_block.id)
+			return None
+
+		system_index = None
+		if db_block.system_prompt_link is not None:
+			system_index = db_block.system_prompt_link.position
+
+		usage = None
+		if getattr(db_block, "usage_json", None):
+			try:
+				usage = TokenUsage.model_validate_json(db_block.usage_json)
+			except Exception:
+				pass
+		timing = None
+		if getattr(db_block, "timing_json", None):
+			try:
+				timing = ResponseTiming.model_validate_json(
+					db_block.timing_json
+				)
+			except Exception:
+				pass
+
+		block = MessageBlock(
+			request=request_msg,
+			response=response_msg,
+			system_index=system_index,
+			model=AIModelInfo(
+				provider_id=db_block.model_provider, model_id=db_block.model_id
+			),
+			temperature=db_block.temperature,
+			max_tokens=db_block.max_tokens,
+			top_p=db_block.top_p,
+			stream=db_block.stream,
+			web_search_mode=getattr(db_block, "web_search_mode", False),
+			usage=usage,
+			timing=timing,
+			created_at=db_block.created_at,
+			updated_at=db_block.updated_at,
+		)
+		block.db_id = db_block.id
+		return block
+
 	def load_conversation(self, conv_id: int) -> Conversation:
 		"""Load a conversation from the database.
 
@@ -684,57 +751,20 @@ def load_conversation(self, conv_id: int) -> Conversation:
 			if db_conv is None:
 				raise ValueError(f"Conversation {conv_id} not found")
 
-			# Rebuild systems OrderedSet
 			systems = PydanticOrderedSet[SystemMessage]()
-			csp_links = sorted(
+			for csp in sorted(
 				db_conv.system_prompt_links, key=lambda x: x.position
-			)
-			for csp in csp_links:
+			):
 				sys_msg = SystemMessage(content=csp.system_prompt.content)
 				sys_msg.db_id = csp.system_prompt.id
 				systems.add(sys_msg)
 
-			# Rebuild message blocks
 			blocks = []
-			sorted_blocks = sorted(db_conv.blocks, key=lambda x: x.position)
-			for db_block in sorted_blocks:
-				# Find request and response messages
-				request_msg = None
-				response_msg = None
-				for db_msg in db_block.messages:
-					if db_msg.role == "user":
-						request_msg = self._load_message(db_msg)
-					elif db_msg.role == "assistant":
-						response_msg = self._load_message(db_msg)
-
-				if request_msg is None:
-					log.warning(
-						"Block %d has no request, skipping", db_block.id
-					)
-					continue
-
-				# Determine system_index
-				system_index = None
-				if db_block.system_prompt_link is not None:
-					system_index = db_block.system_prompt_link.position
-
-				block = MessageBlock(
-					request=request_msg,
-					response=response_msg,
-					system_index=system_index,
-					model=AIModelInfo(
-						provider_id=db_block.model_provider,
-						model_id=db_block.model_id,
-					),
-					temperature=db_block.temperature,
-					max_tokens=db_block.max_tokens,
-					top_p=db_block.top_p,
-					stream=db_block.stream,
-					created_at=db_block.created_at,
-					updated_at=db_block.updated_at,
-				)
-				block.db_id = db_block.id
-				blocks.append(block)
+			for db_block in sorted(db_conv.blocks, key=lambda x: x.position):
+				block = self._load_block_from_db(db_block)
+				if block is not None:
+					blocks.append(block)
+
 			return Conversation(
 				messages=blocks,
 				systems=systems,

basilisk/conversation/database/models.py

@@ -98,6 +98,9 @@ class DBMessageBlock(Base):
 	max_tokens: Mapped[int] = mapped_column(default=4096)
 	top_p: Mapped[float] = mapped_column(default=1.0)
 	stream: Mapped[bool] = mapped_column(default=False)
+	web_search_mode: Mapped[bool] = mapped_column(default=False)
+	usage_json: Mapped[str | None] = mapped_column(default=None)
+	timing_json: Mapped[str | None] = mapped_column(default=None)
 	created_at: Mapped[datetime] = mapped_column(
 		default=lambda: datetime.now(timezone.utc)
 	)

basilisk/presenters/conversation_presenter.py

@@ -174,6 +174,9 @@ def get_new_message_block(self) -> MessageBlock | None:
 		stream = view.stream_mode.GetValue()
 		if audio_params.get("output_modality") == "audio":
 			stream = False
+		web_search = False
+		if hasattr(view, "web_search_mode") and view.web_search_mode.IsShown():
+			web_search = view.web_search_mode.GetValue()
 		return MessageBlock(
 			request=Message(
 				role=MessageRoleEnum.USER,
@@ -187,6 +190,7 @@ def get_new_message_block(self) -> MessageBlock | None:
 			top_p=view.top_p_spinner.GetValue(),
 			max_tokens=view.max_tokens_spin_ctrl.GetValue(),
 			stream=stream,
+			web_search_mode=web_search,
 			**reasoning_params,
 			**audio_params,
 		)
@@ -571,6 +575,9 @@ def _build_draft_block(self) -> MessageBlock | None:
 			return None
 		reasoning_params = get_reasoning_params_from_view(view)
 		audio_params = get_audio_params_from_view(view)
+		web_search = False
+		if hasattr(view, "web_search_mode") and view.web_search_mode.IsShown():
+			web_search = view.web_search_mode.GetValue()
 		block = MessageBlock(
 			request=Message(
 				role=MessageRoleEnum.USER,
@@ -585,6 +592,7 @@ def _build_draft_block(self) -> MessageBlock | None:
 			max_tokens=view.max_tokens_spin_ctrl.GetValue(),
 			top_p=view.top_p_spinner.GetValue(),
 			stream=view.stream_mode.GetValue(),
+			web_search_mode=web_search,
 			**reasoning_params,
 			**audio_params,
 		)