# `LlmComposer.CostInfo`
[🔗](https://github.com/doofinder/llm_composer/blob/master/lib/llm_composer/cost_info.ex#L1)

Struct for tracking costs and token usage of LLM API calls.

This module provides a standardized way to track both token usage and financial costs
across different LLM providers. It supports both streaming and non-streaming responses
and can automatically calculate costs when provided with pricing information.

## Pricing Requirements

When providing pricing information, both `input_price_per_million` and `output_price_per_million`
must be provided together. Providing only one will raise an `ArgumentError`.

## Fields

* `:input_tokens` - Number of tokens in the input/prompt
* `:output_tokens` - Number of tokens in the output/completion
* `:total_tokens` - Total tokens used (input + output)
* `:input_cost` - Cost for input tokens (using Decimal for precision)
* `:output_cost` - Cost for output tokens (using Decimal for precision)
* `:total_cost` - Total cost for the request (using Decimal for precision)
* `:cached_tokens` - Cached prompt tokens billed at cache-read pricing when available
* `:currency` - Currency code (e.g., "USD", "EUR")
* `:provider_model` - The actual model used by the provider
* `:provider_name` - The provider that served the request
* `:input_price_per_million` - Price per million input tokens
* `:cache_read_price_per_million` - Price per million cached input tokens
* `:output_price_per_million` - Price per million output tokens
* `:metadata` - Additional provider-specific cost information

## Examples

  # Basic token tracking
  %LlmComposer.CostInfo{
    input_tokens: 150,
    output_tokens: 75,
    total_tokens: 225,
    provider_name: :open_ai
  }

  # With pricing information - costs calculated automatically
  %LlmComposer.CostInfo{
    input_tokens: 150_000,
    output_tokens: 75_000,
    input_price_per_million: Decimal.new("1.0"),
    output_price_per_million: Decimal.new("3.0"),
    currency: "USD",
    provider_name: :open_ai,
    provider_model: "gpt-4o-mini"
  }
  # Will automatically calculate:
  # input_cost: 0.15, output_cost: 0.225, total_cost: 0.375

  # Direct cost specification (bypasses automatic calculation)
  %LlmComposer.CostInfo{
    input_tokens: 150,
    output_tokens: 75,
    input_cost: Decimal.new("0.0015"),
    output_cost: Decimal.new("0.0030"),
    total_cost: Decimal.new("0.0045"),
    currency: "USD",
    provider_name: :open_ai
  }

# `t`

```elixir
@type t() :: %LlmComposer.CostInfo{
  cache_read_price_per_million: Decimal.t() | nil,
  cached_tokens: non_neg_integer() | nil,
  currency: String.t() | nil,
  input_cost: Decimal.t() | nil,
  input_price_per_million: Decimal.t() | nil,
  input_tokens: non_neg_integer(),
  metadata: map(),
  output_cost: Decimal.t() | nil,
  output_price_per_million: Decimal.t() | nil,
  output_tokens: non_neg_integer(),
  provider_model: String.t(),
  provider_name: String.t() | atom(),
  total_cost: Decimal.t() | nil,
  total_tokens: non_neg_integer()
}
```

# `calculate_cost`

```elixir
@spec calculate_cost(Decimal.t() | nil, non_neg_integer() | nil, Decimal.t() | nil) ::
  Decimal.t() | nil
```

# `new`

```elixir
@spec new(
  String.t() | atom(),
  String.t(),
  non_neg_integer(),
  non_neg_integer(),
  keyword()
) :: t()
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*