From f2a66c304355766530a9fbd39e22c2160a348d67 Mon Sep 17 00:00:00 2001
From: Ayinkx <olayinkaawal00@gmail.com>
Date: Wed, 28 Oct 2026 12:32:16 +0100
Subject: [PATCH 1/3] fix(billing): label estimated costs in reports

---
 app/templates/billing/usage.html | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/app/templates/billing/usage.html b/app/templates/billing/usage.html
index d12c7ac..7d8526a 100644
--- a/app/templates/billing/usage.html
+++ b/app/templates/billing/usage.html
@@ -62,7 +62,7 @@ <h2 id="totals-heading">Totals</h2>
     <div class="metric"><span class="metric-label">Prompt tokens</span><strong>{{ dashboard.totals.prompt_tokens }}</strong></div>
     <div class="metric"><span class="metric-label">Completion tokens</span><strong>{{ dashboard.totals.completion_tokens }}</strong></div>
     <div class="metric"><span class="metric-label">Operations</span><strong>{{ dashboard.totals['count'] }}</strong></div>
-    <div class="metric"><span class="metric-label">Estimated cost</span><strong>{{ dashboard.currency.symbol }}{{ '%.6f'|format(dashboard.totals.cost_estimate) }}</strong></div>
+    <div class="metric"><span class="metric-label" title="Estimated from the configured price table; not a provider-confirmed charge.">Estimated cost</span><strong title="Estimated from the configured price table; not a provider-confirmed charge." aria-label="Estimated cost, {{ dashboard.currency.code }}">{{ dashboard.currency.symbol }}{{ '%.6f'|format(dashboard.totals.cost_estimate) }}</strong></div>
   </div>
   <p class="sidebar-empty">
     {{ dashboard.totals.priced_records }} of {{ dashboard.totals['count'] }} operations have a known price.
@@ -81,7 +81,7 @@ <h2 id="{{ title|lower|replace(' ', '-') }}-heading">{{ title }}</h2>
         <th scope="col">Prompt</th>
         <th scope="col">Completion</th>
         <th scope="col">Total tokens</th>
-        <th scope="col">Estimated cost</th>
+        <th scope="col" title="Estimated from the configured price table; not a provider-confirmed charge.">Estimated cost</th>
       </tr>
     </thead>
     <tbody>
@@ -92,7 +92,7 @@ <h2 id="{{ title|lower|replace(' ', '-') }}-heading">{{ title }}</h2>
         <td>{{ row.prompt_tokens }}</td>
         <td>{{ row.completion_tokens }}</td>
         <td>{{ row.total_tokens }}</td>
-        <td>{{ dashboard.currency.symbol }}{{ '%.6f'|format(row.cost_estimate) }}</td>
+        <td title="Estimated from the configured price table; not a provider-confirmed charge.">{{ dashboard.currency.symbol }}{{ '%.6f'|format(row.cost_estimate) }}</td>
       </tr>
       {% endfor %}
     </tbody>
@@ -118,7 +118,7 @@ <h2 id="daily-heading">Daily time series</h2>
         <th scope="col">Prompt</th>
         <th scope="col">Completion</th>
         <th scope="col">Total tokens</th>
-        <th scope="col">Estimated cost</th>
+        <th scope="col" title="Estimated from the configured price table; not a provider-confirmed charge.">Estimated cost</th>
       </tr>
     </thead>
     <tbody>
@@ -129,7 +129,7 @@ <h2 id="daily-heading">Daily time series</h2>
         <td>{{ row.prompt_tokens }}</td>
         <td>{{ row.completion_tokens }}</td>
         <td>{{ row.total_tokens }}</td>
-        <td>{{ dashboard.currency.symbol }}{{ '%.6f'|format(row.cost_estimate) }}</td>
+        <td title="Estimated from the configured price table; not a provider-confirmed charge.">{{ dashboard.currency.symbol }}{{ '%.6f'|format(row.cost_estimate) }}</td>
       </tr>
       {% endfor %}
     </tbody>

From 6f4b7dd5ec0030c6f9070012045b706be7c86c01 Mon Sep 17 00:00:00 2001
From: Ayinkx <olayinkaawal00@gmail.com>
Date: Wed, 28 Oct 2026 12:32:20 +0100
Subject: [PATCH 2/3] fix(billing): label estimated costs in reports

---
 app/templates/admin/usage_report.html | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/app/templates/admin/usage_report.html b/app/templates/admin/usage_report.html
index b8b9404..3342502 100644
--- a/app/templates/admin/usage_report.html
+++ b/app/templates/admin/usage_report.html
@@ -75,7 +75,7 @@ <h2 id="report-totals-heading">Filtered totals</h2>
     <div class="metric"><span class="metric-label">Prompt tokens</span><strong>{{ summary.prompt_tokens }}</strong></div>
     <div class="metric"><span class="metric-label">Completion tokens</span><strong>{{ summary.completion_tokens }}</strong></div>
     <div class="metric"><span class="metric-label">Total tokens</span><strong>{{ summary.total_tokens }}</strong></div>
-    <div class="metric"><span class="metric-label">Estimated cost</span><strong>{{ currency.symbol }}{{ '%.6f'|format(summary.cost_estimate) }}</strong></div>
+    <div class="metric"><span class="metric-label" title="Estimated from the configured price table; not a provider-confirmed charge.">Estimated cost</span><strong title="Estimated from the configured price table; not a provider-confirmed charge." aria-label="Estimated cost, {{ currency.code }}">{{ currency.symbol }}{{ '%.6f'|format(summary.cost_estimate) }}</strong></div>
   </div>
   <p class="sidebar-empty">
     {{ summary.priced_records }} of {{ summary['count'] }} rows have a known price.
@@ -97,7 +97,7 @@ <h2 id="report-rows-heading">Usage rows</h2>
         <th scope="col">Model</th>
         <th scope="col">Status</th>
         <th scope="col">Tokens</th>
-        <th scope="col">Estimated cost</th>
+        <th scope="col" title="Estimated from the configured price table; not a provider-confirmed charge.">Estimated cost</th>
       </tr>
     </thead>
     <tbody>
@@ -111,7 +111,7 @@ <h2 id="report-rows-heading">Usage rows</h2>
         <td>{{ row.model or 'unknown' }}</td>
         <td>{{ row.status or 'unknown' }}</td>
         <td>{{ row.total_tokens or 0 }}</td>
-        <td>{% if row.cost_estimate is none %}&mdash;{% else %}{{ currency.symbol }}{{ '%.6f'|format(row.cost_estimate) }}{% endif %}</td>
+        <td title="Estimated from the configured price table; not a provider-confirmed charge.">{% if row.cost_estimate is none %}&mdash;{% else %}{{ currency.symbol }}{{ '%.6f'|format(row.cost_estimate) }}{% endif %}</td>
       </tr>
       {% endfor %}
     </tbody>

From 95f0a82c728972aacb713e800ab8c1b20bc086ed Mon Sep 17 00:00:00 2001
From: Ayinkx <olayinkaawal00@gmail.com>
Date: Wed, 28 Oct 2026 12:32:29 +0100
Subject: [PATCH 3/3] test(billing): assert estimate labels in admin usage
 report

---
 tests/test_admin_usage_report.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/tests/test_admin_usage_report.py b/tests/test_admin_usage_report.py
index 1dbe86d..6cf5f4a 100644
--- a/tests/test_admin_usage_report.py
+++ b/tests/test_admin_usage_report.py
@@ -206,3 +206,17 @@ def test_filters_persist_in_pagination_links(self, client, login):
         html = response.get_data(as_text=True)
         assert "source=chat" in html
         assert f"user_id={user.id}" in html
+
+    def test_cost_values_are_explicitly_labelled_as_estimates(self, client, login):
+        user = _user("cost-reader", "cost-reader@example.com")
+        _admin()
+        _record(user)
+        login(email="admin@example.com")
+
+        response = client.get("/admin/usage/report")
+
+        assert response.status_code == 200
+        html = response.get_data(as_text=True)
+        assert 'title="Estimated from the configured price table; not a provider-confirmed charge."' in html
+        assert 'aria-label="Estimated cost, USD"' in html
+        assert "<th scope=\"col\" title=\"Estimated from the configured price table; not a provider-confirmed charge.\">Estimated cost</th>" in html