feat: add per-conversation duration to Html reports

Author: philipph-askui

src/askui/callbacks/usage_tracking_callback.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from datetime import datetime, timezone
 from typing import TYPE_CHECKING
 
 from opentelemetry import trace
@@ -172,11 +173,22 @@ class StepUsageSummary(UsageSummary):
 
 
 class ConversationUsageSummary(UsageSummary):
-    """Usage summary for one conversation including per-step breakdown."""
+    """Usage summary for one conversation including per-step breakdown.
+
+    Args:
+        conversation_index (int): 1-based index of the conversation within the
+            current agent lifecycle.
+        conversation_id (str): Unique identifier of the conversation.
+        step_summaries (list[StepUsageSummary]): Per-step usage summaries.
+        duration_seconds (float | None): Wall-clock duration of the conversation
+            in seconds, measured between `on_conversation_start` and
+            `on_conversation_end`. `None` if duration was not tracked.
+    """
 
     conversation_index: int
     conversation_id: str
     step_summaries: list[StepUsageSummary] = Field(default_factory=list)
+    duration_seconds: float | None = None
 
 
 class UsageTrackingCallback(ConversationCallback):
@@ -199,12 +211,14 @@ def __init__(
         self._per_conversation_summaries: list[ConversationUsageSummary] = []
         self._per_step_summaries: list[StepUsageSummary] = []
         self._conversation_index: int = 0
+        self._conversation_start_time: datetime | None = None
 
     @override
     def on_conversation_start(self, conversation: Conversation) -> None:
         self._per_conversation_usage = UsageSummary.create_from(self._summary)
         self._per_step_summaries = []
         self._conversation_index += 1
+        self._conversation_start_time = datetime.now(tz=timezone.utc)
 
     @override
     def on_step_end(
@@ -237,9 +251,15 @@ def on_conversation_end(self, conversation: Conversation) -> None:
         generated_steps: list[StepUsageSummary] = [
             step_summary.generate() for step_summary in self._per_step_summaries
         ]
+        duration_seconds: float | None = None
+        if self._conversation_start_time is not None:
+            duration_seconds = (
+                datetime.now(tz=timezone.utc) - self._conversation_start_time
+            ).total_seconds()
         conversation_summary = self._create_conversation_summary(
             conversation=conversation,
             generated_step_summaries=generated_steps,
+            duration_seconds=duration_seconds,
         )
         self._per_conversation_summaries.append(conversation_summary)
         self._summary.per_conversation_summaries = list(
@@ -275,11 +295,13 @@ def _create_conversation_summary(
         self,
         conversation: Conversation,
         generated_step_summaries: list[StepUsageSummary],
+        duration_seconds: float | None = None,
     ) -> ConversationUsageSummary:
         conversation_summary = ConversationUsageSummary(
             conversation_index=self._conversation_index,
             conversation_id=conversation.conversation_id,
             step_summaries=generated_step_summaries,
+            duration_seconds=duration_seconds,
             input_tokens=self._per_conversation_usage.input_tokens,
             output_tokens=self._per_conversation_usage.output_tokens,
             cache_creation_input_tokens=(

src/askui/reporting.py

@@ -37,6 +37,27 @@ def normalize_to_pil_images(
     return [image]
 
 
+def _format_duration(seconds: float) -> str:
+    """Format a duration given in seconds as ``HH:MM:SS`` or
+    ``HH:MM:SS.mmm`` for sub-second precision.
+
+    Used by `SimpleHtmlReporter` to render both the overall execution time and
+    per-conversation durations consistently.
+    """
+    total_seconds = max(float(seconds), 0.0)
+    whole_seconds = int(total_seconds)
+    millis = int(round((total_seconds - whole_seconds) * 1000))
+    if millis == 1000:
+        whole_seconds += 1
+        millis = 0
+    hours, remainder = divmod(whole_seconds, 3600)
+    minutes, secs = divmod(remainder, 60)
+    base = f"{hours:02d}:{minutes:02d}:{secs:02d}"
+    if whole_seconds == 0 and millis > 0:
+        return f"{base}.{millis:03d}"
+    return base
+
+
 def truncate_base64_images(content: Any) -> Any:
     """Replace base64 image data with a placeholder to keep reports readable.
 
@@ -1010,6 +1031,9 @@ def generate(self) -> None:
                                     </span>
                                     <span class="usage-breakdown-meta">
                                         {{ conversation_usage.step_summaries | length }} step(s),
+                                        {% if conversation_usage.duration_seconds is not none %}
+                                            Duration: {{ format_duration(conversation_usage.duration_seconds) }},
+                                        {% endif %}
                                         Input {{ "{:,}".format(conversation_usage.input_tokens or 0) }},
                                         Output {{ "{:,}".format(conversation_usage.output_tokens or 0) }},
                                         Cache Create {{ "{:,}".format(conversation_usage.cache_creation_input_tokens or 0) }},
@@ -1026,6 +1050,9 @@ def generate(self) -> None:
                                     <table class="nested-table">
                                         <tr>
                                             <th>Conversation ID</th>
+                                            {% if conversation_usage.duration_seconds is not none %}
+                                            <th>Duration</th>
+                                            {% endif %}
                                             <th>Input Tokens</th>
                                             <th>Output Tokens</th>
                                             <th>Cache Create</th>
@@ -1036,6 +1063,9 @@ def generate(self) -> None:
                                         </tr>
                                         <tr class="system">
                                             <td class="mono">{{ conversation_usage.conversation_id }}</td>
+                                            {% if conversation_usage.duration_seconds is not none %}
+                                            <td>{{ format_duration(conversation_usage.duration_seconds) }}</td>
+                                            {% endif %}
                                             <td>{{ "{:,}".format(conversation_usage.input_tokens or 0) }}</td>
                                             <td>{{ "{:,}".format(conversation_usage.output_tokens or 0) }}</td>
                                             <td>{{ "{:,}".format(conversation_usage.cache_creation_input_tokens or 0) }}</td>
@@ -1141,10 +1171,9 @@ def generate(self) -> None:
         end_time = datetime.now(tz=timezone.utc)
         execution_time_formatted: str | None = None
         if self._start_time is not None:
-            total_secs = int((end_time - self._start_time).total_seconds())
-            hours, remainder = divmod(total_secs, 3600)
-            minutes, secs = divmod(remainder, 60)
-            execution_time_formatted = f"{hours:02d}:{minutes:02d}:{secs:02d}"
+            execution_time_formatted = _format_duration(
+                (end_time - self._start_time).total_seconds()
+            )
 
         html = template.render(
             timestamp=end_time,
@@ -1153,6 +1182,7 @@ def generate(self) -> None:
             usage_summary=self.usage_summary,
             cache_original_usage=self.cache_original_usage,
             execution_time_formatted=execution_time_formatted,
+            format_duration=_format_duration,
         )
 
         report_path = (

tests/unit/model_providers/test_model_pricing.py

@@ -245,6 +245,8 @@ def test_tracks_per_step_per_conversation_and_total_usage(self) -> None:
         assert per_conversation_summary.output_tokens == 30
         _assert_close(per_conversation_summary.total_cost, 0.0009)
         assert len(per_conversation_summary.step_summaries) == 2
+        assert per_conversation_summary.duration_seconds is not None
+        assert per_conversation_summary.duration_seconds >= 0.0
 
         first_step = per_conversation_summary.step_summaries[0]
         assert first_step.step_index == 0
@@ -301,6 +303,9 @@ def test_accumulates_multiple_conversations(self) -> None:
         assert len(summary.per_conversation_summaries) == 2
         assert summary.per_conversation_summaries[0].conversation_id == "conversation-1"
         assert summary.per_conversation_summaries[1].conversation_id == "conversation-2"
+        for per_conversation_summary in summary.per_conversation_summaries:
+            assert per_conversation_summary.duration_seconds is not None
+            assert per_conversation_summary.duration_seconds >= 0.0
 
     def test_includes_cache_costs_from_provider_pricing(self) -> None:
         pricing = ModelPricing(