# `LangChain.TokenUsage`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/token_usage.ex#L1)

Contains token usage information returned from an LLM.

## Example

    %TokenUsage{
      input: 30,
      output: 15,
      raw: %{
        "total_tokens" => 29
      }
    }

Input is the tokens from the prompt. Output is the completion or generated
tokens returned.

Refer to the `raw` token usage information for access to LLM-specific information that may be available.

# `t`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/token_usage.ex#L38)

```elixir
@type t() :: %LangChain.TokenUsage{
  cumulative: term(),
  input: term(),
  output: term(),
  raw: term()
}
```

# `add`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/token_usage.ex#L105)

```elixir
@spec add(t() | nil, t() | nil) :: t() | nil
```

Combines two TokenUsage structs by adding their respective input and output values.
The raw maps are merged, with values being added if they are numeric.

If both arguments are nil, returns nil.
If one argument is nil, returns the non-nil argument.

## Example

    iex> usage1 = LangChain.TokenUsage.new!(%{input: 10, output: 20, raw: %{"total_tokens" => 30}})
    iex> usage2 = LangChain.TokenUsage.new!(%{input: 5, output: 15, raw: %{"total_tokens" => 20}})
    iex> combined = LangChain.TokenUsage.add(usage1, usage2)
    iex> combined.input
    15
    iex> combined.output
    35
    iex> combined.raw["total_tokens"]
    50

# `get`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/token_usage.ex#L142)

```elixir
@spec get(%{metadata: %{usage: t()}} | %{metadata: map() | nil}) :: t() | nil
```

Extracts token usage information from a `LangChain.Message` or
`LangChain.MessageDelta` struct's metadata. Returns nil if no token usage
information is found.

## Example

    iex> message = %LangChain.Message{metadata: %{usage: %LangChain.TokenUsage{input: 10, output: 20}}}
    iex> LangChain.TokenUsage.get(message)
    %LangChain.TokenUsage{input: 10, output: 20}

    iex> message = %LangChain.Message{metadata: %{}}
    iex> LangChain.TokenUsage.get(message)
    nil

# `new`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/token_usage.ex#L48)

```elixir
@spec new(attrs :: map()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}
```

Build a new TokenUsage and return an `:ok`/`:error` tuple with the result.

# `new!`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/token_usage.ex#L59)

```elixir
@spec new!(attrs :: map()) :: t() | no_return()
```

Build a new TokenUsage and return it or raise an error if invalid.

# `set`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/token_usage.ex#L157)

```elixir
@spec set(t() | %{metadata: %{usage: t()}}, nil | t()) ::
  t() | %{metadata: %{usage: t()}}
```

Sets the token usage information on a `LangChain.Message` or
`LangChain.MessageDelta` struct in the `metadata` under the `:usage` key.

## Example

    iex> message = %LangChain.Message{metadata: %{}}
    iex> token_usage = %LangChain.TokenUsage{input: 10, output: 20}
    iex> LangChain.TokenUsage.set(message, token_usage)
    %LangChain.Message{metadata: %{usage: %LangChain.TokenUsage{input: 10, output: 20}}}

# `set_wrapped`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/token_usage.ex#L176)

```elixir
@spec set_wrapped(
  {:ok, %{metadata: nil | map()}},
  nil | t()
) :: {:ok, %{metadata: %{usage: t()}} | {:error, any()}}
```

Sets the token usage information on a `LangChain.Message` or
`LangChain.MessageDelta` struct when wrapped in an :ok,:error tuple in the `metadata` under the `:usage` key.

# `total`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/token_usage.ex#L80)

```elixir
@spec total(t()) :: integer()
```

Return the total token usage amount. The total is the sum of input and output.

---

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