par_ai_core.pricing_lookup API documentation
Description: Pricing Lookup and Cost Calculation Module …

# Module `par_ai_core.pricing_lookup`

Pricing Lookup and Cost Calculation Module

This module provides functionality for managing and calculating costs associated with various AI language models across different providers. It includes:

- A comprehensive pricing lookup table for different AI models
- Functions to calculate API call costs based on usage
- Utilities for accumulating and displaying cost information

Key components: - pricing_lookup: A dictionary containing pricing details for various AI models - PricingDisplay: An enum for controlling the level of cost display detail - Functions for cost calculation, usage metadata management, and cost display

## Usage

from par_ai_core.pricing_lookup import get_api_call_cost, show_llm_cost

# Calculate cost for an API call

cost = get_api_call_cost(llm_config, usage_metadata)

# Display cost information

show_llm_cost(usage_metadata, show_pricing=PricingDisplay.DETAILS)

This module is essential for tracking and managing costs in AI-powered applications, especially when working with multiple AI providers and models.

## Functions

`def accumulate_cost(response: object | dict, usage_metadata: dict[str, int | float]) ‑> None`
  Expand source code

      def accumulate_cost(response: object | dict, usage_metadata: dict[str, int | float]) -> None:
          if isinstance(response, dict):
              usage_metadata["input_tokens"] += response.get("input_tokens", 0)
              usage_metadata["output_tokens"] += response.get("output_tokens", 0)
              usage_metadata["total_tokens"] += response.get("input_tokens", 0) + response.get("output_tokens", 0)
              usage_metadata["cache_write"] += response.get("cache_creation_input_tokens", 0)
              usage_metadata["cache_read"] += response.get("cache_read_input_tokens", 0)
              return

          if hasattr(response, "usage_metadata"):
              for key, value in response.usage_metadata.items():  # type: ignore
                  if key in usage_metadata:
                      usage_metadata[key] += value
                  if key == "input_token_details":
                      usage_metadata["cache_write"] += value.get("cache_creation", 0)
                      usage_metadata["cache_read"] += value.get("cache_read", value.get("cache_read", 0))
                  if key == "output_token_details":
                      usage_metadata["reasoning"] += value.get("reasoning", 0)

`def get_api_call_cost(*,
llm_config: LlmConfig,
usage_metadata: dict[str, int | float],
batch_pricing: bool = False,
model_name_override: str | None = None) ‑> float`
  Expand source code

      def get_api_call_cost(
          *,
          llm_config: LlmConfig,
          usage_metadata: dict[str, int | float],
          batch_pricing: bool = False,
          model_name_override: str | None = None,
      ) -> float:
          """Calculate the cost of API calls based on usage.

          Computes the total cost of API usage taking into account:
          - Input and output tokens
          - Cache operations
          - Provider-specific pricing
          - Batch pricing discounts if applicable

          Args:
              llm_config: Configuration of the LLM used
              usage_metadata: Dictionary containing usage statistics
              batch_pricing: Whether to apply batch pricing discount
              model_name_override: Override the model name for pricing calculations

          Returns:
              Total cost in USD
          """
          if llm_config.provider in [LlmProvider.OLLAMA, LlmProvider.LLAMACPP, LlmProvider.GROQ, LlmProvider.GITHUB]:
              return 0
          batch_multiplier = 0.5 if batch_pricing else 1
          model_name = get_api_cost_model_name(model_name_override or llm_config.model_name)
          # console_err.print(f"price model name {model_name}")

          if model_name in pricing_lookup:
              total_cost = (
                  (
                      (usage_metadata["input_tokens"] - usage_metadata["cache_read"] - usage_metadata["cache_write"])
                      * pricing_lookup[model_name]["input"]
                  )
                  + (
                      usage_metadata["cache_read"]
                      * pricing_lookup[model_name]["input"]
                      * pricing_lookup[model_name]["cache_read"]
                  )
                  + (
                      usage_metadata["cache_write"]
                      * pricing_lookup[model_name]["input"]
                      * pricing_lookup[model_name]["cache_write"]
                  )
                  + (usage_metadata["output_tokens"] * pricing_lookup[model_name]["output"])
              )
              return total_cost * batch_multiplier
          # else:
          #     console_err.print(f"No pricing data found for model {model_name}")

          return 0

  Calculate the cost of API calls based on usage.

  Computes the total cost of API usage taking into account: - Input and output tokens - Cache operations - Provider-specific pricing - Batch pricing discounts if applicable

  ## Args

  `llm_config`
    Configuration of the LLM used
  `usage_metadata`
    Dictionary containing usage statistics
  `batch_pricing`
    Whether to apply batch pricing discount
  `model_name_override`
    Override the model name for pricing calculations

  ## Returns

  Total cost in USD

`def get_api_cost_model_name(model_name: str = '') ‑> str`
  Expand source code

      def get_api_cost_model_name(model_name: str = "") -> str:
          """Get API cost model name"""
          if "/" in model_name:
              model_name = model_name.split("/")[-1]
          if model_name not in pricing_lookup:
              keys = pricing_lookup.keys()
              keys = sorted(keys, key=len, reverse=True)
              for key in keys:
                  if key.endswith(model_name) or model_name.endswith(key):
                      model_name = key
                      break
              if not model_name:
                  for key in keys:
                      if key.startswith(model_name) or model_name.startswith(key):
                          model_name = key
                          break

          return model_name

  Get API cost model name

`def mk_usage_metadata() ‑> dict[str, int | float]`
  Expand source code

      def mk_usage_metadata() -> dict[str, int | float]:
          """Create a new usage metadata dictionary.

          Initializes a dictionary to track various usage metrics including:
          token counts, cache operations, tool calls, and costs.

          Returns:
              Dictionary with usage tracking fields initialized to zero
          """
          return {
              "input_tokens": 0,
              "output_tokens": 0,
              "total_tokens": 0,
              "cache_write": 0,
              "cache_read": 0,
              "reasoning": 0,
              "successful_requests": 0,
              "tool_call_count": 0,
              "total_cost": 0.0,
          }

  Create a new usage metadata dictionary.

  Initializes a dictionary to track various usage metrics including: token counts, cache operations, tool calls, and costs.

  ## Returns

  Dictionary with usage tracking fields initialized to zero

`def show_llm_cost(usage_metadata: dict[str, dict[str, int | float]],
*,
show_pricing: PricingDisplay = price,
console: rich.console.Console | None = None) ‑> None`
  Expand source code

      def show_llm_cost(
          usage_metadata: dict[str, dict[str, int | float]],
          *,
          show_pricing: PricingDisplay = PricingDisplay.PRICE,
          console: Console | None = None,
      ) -> None:
          """Show LLM cost"""
          if show_pricing == PricingDisplay.NONE:
              return
          if not console:
              console = console_err
          grand_total: float = 0.0
          if show_pricing == PricingDisplay.PRICE:
              for m, u in usage_metadata.items():
                  if "total_cost" in u:
                      grand_total += u["total_cost"]
          else:
              for m, u in usage_metadata.items():
                  cost = 0.0
                  if "total_cost" in u:
                      cost = u["total_cost"]
                      grand_total += cost
                  model_name = get_api_cost_model_name(m)
                  console.print(
                      Panel.fit(
                          Pretty(u),
                          title=f"Model: [green]{model_name}[/green] Cost: [yellow]${cost:.5f}",
                          border_style="bold",
                      )
                  )
          console.print(f"Total Cost [yellow]${grand_total:.4f}")

  Show LLM cost

## Classes

`class PricingDisplay (*args, **kwds)`
  Expand source code

      class PricingDisplay(StrEnum):
          NONE = "none"
          PRICE = "price"
          DETAILS = "details"

  StrEnum is a Python `enum.Enum` that inherits from `str`. The default `auto()` behavior uses the member name as its value.

  Example usage::

      class Example(StrEnum):
          UPPER_CASE = auto()
          lower_case = auto()
          MixedCase = auto()

      assert Example.UPPER_CASE == "UPPER_CASE"
      assert Example.lower_case == "lower_case"
      assert Example.MixedCase == "MixedCase"

  ### Ancestors

  - strenum.StrEnum
  - builtins.str
  - enum.Enum

  ### Class variables

  `var DETAILS`
  `var NONE`
  `var PRICE`