feat: add pricing to html reports

Author: philipph-askui

docs/05_bring_your_own_model_provider.md

@@ -135,6 +135,49 @@ class MyImageQAProvider(ImageQAProvider):
 ```
 
 
+### Execution Cost Tracking
+
+If you want execution cost tracking in your reports, override the `pricing` property on your custom `VlmProvider`:
+
+```python
+from typing import Any
+from typing_extensions import override
+from askui.model_providers import VlmProvider, ModelPricing
+from askui.models.shared.agent_message_param import MessageParam, ThinkingConfigParam, ToolChoiceParam
+from askui.models.shared.prompts import SystemPrompt
+from askui.models.shared.tools import ToolCollection
+
+
+class MyVlmProvider(VlmProvider):
+    @property
+    def model_id(self) -> str:
+        return "my-model-v1"
+
+    @property
+    @override
+    def pricing(self) -> ModelPricing | None:
+        return ModelPricing(
+            input_cost_per_million_tokens=1.0,
+            output_cost_per_million_tokens=5.0,
+        )
+
+    @override
+    def create_message(
+        self,
+        messages: list[MessageParam],
+        tools: ToolCollection | None = None,
+        max_tokens: int | None = None,
+        system: SystemPrompt | None = None,
+        thinking: ThinkingConfigParam | None = None,
+        tool_choice: ToolChoiceParam | None = None,
+        temperature: float | None = None,
+        provider_options: dict[str, Any] | None = None,
+    ) -> MessageParam:
+        ...  # call your API here
+```
+
+---
+
 ## Advanced: Injecting a Custom Client
 
 For full control over HTTP settings (timeouts, proxies, retries), you can inject a pre-configured client:

docs/08_reporting.md

@@ -32,6 +32,35 @@ This generates an HTML file (typically in the current directory) showing:
 SimpleHtmlReporter(output_dir="./execution_reports", filename="agent_run.html")
 ```
 
+### Execution Cost Tracking
+
+The HTML report automatically shows the estimated API cost when using a `VlmProvider` with pricing information. The built-in Anthropic and AskUI providers include default pricing for supported Claude models.
+
+To override pricing (for example, if you have a custom pricing agreement):
+
+```python
+from askui import AgentSettings, ComputerAgent
+from askui.model_providers import AnthropicVlmProvider
+from askui.reporting import SimpleHtmlReporter
+
+with ComputerAgent(
+    reporters=[SimpleHtmlReporter()],
+    settings=AgentSettings(
+        vlm_provider=AnthropicVlmProvider(
+            model_id="claude-sonnet-4-6",
+            input_cost_per_million_tokens=2.5,
+            output_cost_per_million_tokens=12.0,
+        ),
+    ),
+) as agent:
+    agent.act("Open settings")
+```
+
+The report will display:
+- Total estimated cost
+- Per-token rates used for the calculation
+- Input and output token breakdowns (as before)
+
 ### Custom Reporters
 
 Create custom reporters by implementing the `Reporter` interface:

src/askui/agent_base.py

@@ -75,7 +75,12 @@ def __init__(
         # Create conversation with speakers and model providers
         speakers = Speakers()
         _callbacks = list(callbacks or [])
-        _callbacks.append(UsageTrackingCallback(reporter=self._reporter))
+        _callbacks.append(
+            UsageTrackingCallback(
+                reporter=self._reporter,
+                pricing=self._vlm_provider.pricing,
+            )
+        )
         self._conversation = Conversation(
             speakers=speakers,
             vlm_provider=self._vlm_provider,

src/askui/model_providers/__init__.py

@@ -23,6 +23,7 @@
 from askui.model_providers.google_image_qa_provider import GoogleImageQAProvider
 from askui.model_providers.image_qa_provider import ImageQAProvider
 from askui.model_providers.vlm_provider import VlmProvider
+from askui.utils.model_pricing import ModelPricing
 
 __all__ = [
     "AnthropicImageQAProvider",
@@ -33,5 +34,6 @@
     "DetectionProvider",
     "GoogleImageQAProvider",
     "ImageQAProvider",
+    "ModelPricing",
     "VlmProvider",
 ]

src/askui/model_providers/anthropic_vlm_provider.py

@@ -16,6 +16,7 @@
 )
 from askui.models.shared.prompts import SystemPrompt
 from askui.models.shared.tools import ToolCollection
+from askui.utils.model_pricing import ModelPricing, resolve_default_pricing
 
 _DEFAULT_MODEL_ID = "claude-sonnet-4-6"
 
@@ -38,6 +39,11 @@ class AnthropicVlmProvider(VlmProvider):
             `\"claude-sonnet-4-6\"`.
         client (Anthropic | None, optional): Pre-configured Anthropic client.
             If provided, other connection parameters are ignored.
+        input_cost_per_million_tokens (float | None, optional): Override
+            cost in USD per 1M input tokens. Both cost params must be set
+            to override the built-in defaults.
+        output_cost_per_million_tokens (float | None, optional): Override
+            cost in USD per 1M output tokens.
 
     Example:
         ```python
@@ -60,6 +66,8 @@ def __init__(
         auth_token: str | None = None,
         model_id: str | None = None,
         client: Anthropic | None = None,
+        input_cost_per_million_tokens: float | None = None,
+        output_cost_per_million_tokens: float | None = None,
     ) -> None:
         self._model_id_value = (
             model_id or os.environ.get("VLM_PROVIDER_MODEL_ID") or _DEFAULT_MODEL_ID
@@ -72,12 +80,28 @@ def __init__(
                 base_url=base_url,
                 auth_token=auth_token,
             )
+        self._pricing: ModelPricing | None
+        if (
+            input_cost_per_million_tokens is not None
+            and output_cost_per_million_tokens is not None
+        ):
+            self._pricing = ModelPricing(
+                input_cost_per_million_tokens=input_cost_per_million_tokens,
+                output_cost_per_million_tokens=output_cost_per_million_tokens,
+            )
+        else:
+            self._pricing = resolve_default_pricing(self._model_id_value)
 
     @property
     @override
     def model_id(self) -> str:
         return self._model_id_value
 
+    @property
+    @override
+    def pricing(self) -> ModelPricing | None:
+        return self._pricing
+
     @cached_property
     def _messages_api(self) -> AnthropicMessagesApi:
         """Lazily initialise the AnthropicMessagesApi on first use."""

src/askui/model_providers/askui_vlm_provider.py

@@ -17,6 +17,7 @@
 )
 from askui.models.shared.prompts import SystemPrompt
 from askui.models.shared.tools import ToolCollection
+from askui.utils.model_pricing import ModelPricing, resolve_default_pricing
 
 _DEFAULT_MODEL_ID = "claude-sonnet-4-6"
 
@@ -37,6 +38,11 @@ class AskUIVlmProvider(VlmProvider):
             `"claude-sonnet-4-6"`.
         client (Anthropic | None, optional): Pre-configured Anthropic client.
             If provided, `workspace_id` and `token` are ignored.
+        input_cost_per_million_tokens (float | None, optional): Override
+            cost in USD per 1M input tokens. Both cost params must be set
+            to override the built-in defaults.
+        output_cost_per_million_tokens (float | None, optional): Override
+            cost in USD per 1M output tokens.
 
     Example:
         ```python
@@ -58,18 +64,36 @@ def __init__(
         askui_settings: AskUiInferenceApiSettings | None = None,
         model_id: str | None = None,
         client: Anthropic | None = None,
+        input_cost_per_million_tokens: float | None = None,
+        output_cost_per_million_tokens: float | None = None,
     ) -> None:
         self._askui_settings = askui_settings or AskUiInferenceApiSettings()
         self._model_id_value = (
             model_id or os.environ.get("VLM_PROVIDER_MODEL_ID") or _DEFAULT_MODEL_ID
         )
         self._injected_client = client
+        self._pricing: ModelPricing | None
+        if (
+            input_cost_per_million_tokens is not None
+            and output_cost_per_million_tokens is not None
+        ):
+            self._pricing = ModelPricing(
+                input_cost_per_million_tokens=input_cost_per_million_tokens,
+                output_cost_per_million_tokens=output_cost_per_million_tokens,
+            )
+        else:
+            self._pricing = resolve_default_pricing(self._model_id_value)
 
     @property
     @override
     def model_id(self) -> str:
         return self._model_id_value
 
+    @property
+    @override
+    def pricing(self) -> ModelPricing | None:
+        return self._pricing
+
     @cached_property
     def _messages_api(self) -> AnthropicMessagesApi:
         """Lazily initialise the AnthropicMessagesApi on first use."""

src/askui/model_providers/vlm_provider.py

@@ -10,6 +10,7 @@
 )
 from askui.models.shared.prompts import SystemPrompt
 from askui.models.shared.tools import ToolCollection
+from askui.utils.model_pricing import ModelPricing
 
 
 class VlmProvider(ABC):
@@ -43,6 +44,15 @@ class VlmProvider(ABC):
     def model_id(self) -> str:
         """The model identifier used by this provider."""
 
+    @property
+    def pricing(self) -> ModelPricing | None:
+        """Pricing information for this provider's model.
+
+        Returns ``None`` if no pricing information is available.
+        Override in subclasses to provide model-specific pricing.
+        """
+        return None
+
     @abstractmethod
     def create_message(
         self,

src/askui/models/shared/usage_tracking_callback.py

@@ -14,17 +14,25 @@
 if TYPE_CHECKING:
     from askui.models.shared.conversation import Conversation
     from askui.speaker.speaker import SpeakerResult
+    from askui.utils.model_pricing import ModelPricing
 
 
 class UsageTrackingCallback(ConversationCallback):
     """Tracks token usage per step and reports a summary at conversation end.
 
     Args:
         reporter: Reporter to write the final usage summary to.
+        pricing: Pricing information for cost calculation. If ``None``,
+            no cost data is included in the usage summary.
     """
 
-    def __init__(self, reporter: Reporter = NULL_REPORTER) -> None:
+    def __init__(
+        self,
+        reporter: Reporter = NULL_REPORTER,
+        pricing: ModelPricing | None = None,
+    ) -> None:
         self._reporter = reporter
+        self._pricing = pricing
         self._accumulated_usage = UsageParam()
 
     @override
@@ -43,7 +51,27 @@ def on_step_end(
 
     @override
     def on_conversation_end(self, conversation: Conversation) -> None:
-        self._reporter.add_usage_summary(self._accumulated_usage.model_dump())
+        usage_dict = self._accumulated_usage.model_dump()
+        if self._pricing is not None:
+            input_tokens = self._accumulated_usage.input_tokens or 0
+            output_tokens = self._accumulated_usage.output_tokens or 0
+            input_cost = (
+                input_tokens * self._pricing.input_cost_per_million_tokens / 1_000_000
+            )
+            output_cost = (
+                output_tokens * self._pricing.output_cost_per_million_tokens / 1_000_000
+            )
+            usage_dict["input_cost"] = input_cost
+            usage_dict["output_cost"] = output_cost
+            usage_dict["total_cost"] = input_cost + output_cost
+            usage_dict["currency"] = self._pricing.currency
+            usage_dict["input_cost_per_million_tokens"] = (
+                self._pricing.input_cost_per_million_tokens
+            )
+            usage_dict["output_cost_per_million_tokens"] = (
+                self._pricing.output_cost_per_million_tokens
+            )
+        self._reporter.add_usage_summary(usage_dict)
 
     @property
     def accumulated_usage(self) -> UsageParam:

src/askui/reporting.py

@@ -824,6 +824,18 @@ def generate(self) -> None:
                                     </td>
                                 </tr>
                                 {% endif %}
+                                {% if usage_summary.get('total_cost') is not none %}
+                                <tr>
+                                    <th>Estimated Cost</th>
+                                    <td>
+                                        {{ "%.2f"|format(usage_summary.get('total_cost')) }} {{ usage_summary.get('currency', 'USD') }}
+                                        <span style="color: var(--text-muted); margin-left: 8px; font-size: 0.85em;">
+                                            (Input: ${{ "%.2f"|format(usage_summary.get('input_cost_per_million_tokens', 0)) }}/1M tokens,
+                                             Output: ${{ "%.2f"|format(usage_summary.get('output_cost_per_million_tokens', 0)) }}/1M tokens)
+                                        </span>
+                                    </td>
+                                </tr>
+                                {% endif %}
                             {% endif %}
                             {% if cache_original_usage is not none %}
                                 {% if cache_original_usage.get('input_tokens') is not none %}

src/askui/utils/model_pricing.py

@@ -0,0 +1,57 @@
+"""Pricing information for model API calls."""
+
+from pydantic import BaseModel
+
+
+class ModelPricing(BaseModel):
+    """Cost per 1 million tokens for a model.
+
+    Args:
+        input_cost_per_million_tokens (float): Cost in USD per 1M input tokens.
+        output_cost_per_million_tokens (float): Cost in USD per 1M output tokens.
+        currency (str): ISO 4217 currency code. Defaults to ``"USD"``.
+    """
+
+    input_cost_per_million_tokens: float
+    output_cost_per_million_tokens: float
+    currency: str = "USD"
+
+
+_DEFAULT_PRICING: dict[str, ModelPricing] = {
+    "claude-haiku-4-5-20251001": ModelPricing(
+        input_cost_per_million_tokens=1.0,
+        output_cost_per_million_tokens=5.0,
+    ),
+    "claude-sonnet-4-5-20250929": ModelPricing(
+        input_cost_per_million_tokens=3.0,
+        output_cost_per_million_tokens=15.0,
+    ),
+    "claude-opus-4-5-20251101": ModelPricing(
+        input_cost_per_million_tokens=5.0,
+        output_cost_per_million_tokens=25.0,
+    ),
+    "claude-sonnet-4-6": ModelPricing(
+        input_cost_per_million_tokens=3.0,
+        output_cost_per_million_tokens=15.0,
+    ),
+    "claude-opus-4-6": ModelPricing(
+        input_cost_per_million_tokens=5.0,
+        output_cost_per_million_tokens=25.0,
+    ),
+}
+
+
+def resolve_default_pricing(model_id: str) -> ModelPricing | None:
+    """Resolve default pricing for a model ID by prefix matching.
+
+    Tries exact match first, then longest-prefix match.
+
+    Args:
+        model_id (str): The model identifier.
+
+    Returns:
+        ModelPricing | None: Default pricing, or ``None`` if no match found.
+    """
+    if model_id in _DEFAULT_PRICING:
+        return _DEFAULT_PRICING[model_id]
+    return None