@spec accumulate_token_usage(t(), t()) :: t()

Accumulates token usage from delta messages. Uses LangChain.TokenUsage.add/2 to combine the usage data from both deltas.

Example

iex> alias LangChain.TokenUsage
iex> alias LangChain.MessageDelta
iex> delta1 = %MessageDelta{
...>   metadata: %{
...>     usage: %TokenUsage{input: 10, output: 5}
...>   }
...> }
iex> delta2 = %MessageDelta{
...>   metadata: %{
...>     usage: %TokenUsage{input: 5, output: 15}
...>   }
...> }
iex> result = MessageDelta.accumulate_token_usage(delta1, delta2)
iex> result.metadata.usage.input
15
iex> result.metadata.usage.output
20

@spec content_to_string(t(), type :: atom()) :: nil | String.t()

Convert the MessageDelta's merged content to a string. Specify the type of content to convert so it can return just the text parts or thinking parts, etc. Defaults to :text.

@spec merge_delta(nil | t(), t()) :: t()

Merge two MessageDelta structs. The first MessageDelta is the primary one that smaller deltas are merged into.

The merging process:

1. Migrates any string content to ContentParts for backward compatibility
2. Merges the content into merged_content based on the index field
3. Clears the content field (sets to nil) after merging
4. Updates other fields (tool_calls, status, etc.)

Examples

iex> delta_1 =
...>   %LangChain.MessageDelta{
...>     content: nil,
...>     index: 0,
...>     tool_calls: [],
...>     role: :assistant,
...>     status: :incomplete
...>   }
iex> delta_2 =
...>   %LangChain.MessageDelta{
...>     content: "Hello",
...>     index: 0,
...>     tool_calls: [],
...>     role: :unknown,
...>     status: :incomplete
...>   }
iex> LangChain.MessageDelta.merge_delta(delta_1, delta_2)
%LangChain.MessageDelta{
  content: nil,
  merged_content: [%LangChain.Message.ContentPart{type: :text, content: "Hello"}],
  status: :incomplete,
  index: 0,
  role: :assistant,
  tool_calls: []
}

A set of deltas can be easily merged like this:

  MessageDelta.merge_deltas(list_of_delta_messages)

@spec merge_deltas([t()]) :: t()

Merges a list of MessageDeltas into a single MessageDelta. The deltas are merged in order, with each delta being merged into the result of the previous merge.

Examples

iex> deltas = [
...>   %LangChain.MessageDelta{content: "Hello", role: :assistant},
...>   %LangChain.MessageDelta{content: " world", role: :assistant},
...>   %LangChain.MessageDelta{content: "!", role: :assistant, status: :complete}
...> ]
iex> LangChain.MessageDelta.merge_deltas(deltas)
%LangChain.MessageDelta{
  content: nil,
  merged_content: [%LangChain.Message.ContentPart{type: :text, content: "Hello world!"}],
  status: :complete,
  role: :assistant
}

@spec migrate_to_content_parts(t()) :: t()

Migrates a MessageDelta's string content to use LangChain.Message.ContentPart. This is for backward compatibility with models that don't yet support ContentPart streaming.

Examples

iex> delta = %LangChain.MessageDelta{content: "Hello world"}
iex> upgraded = migrate_to_content_parts(delta)
iex> upgraded.content
%LangChain.Message.ContentPart{type: :text, content: "Hello world"}

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

Create a new MessageDelta that represents a message chunk.

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

Create a new MessageDelta that represents a message chunk and return it or raise an error if invalid.

@spec to_message(t()) :: {:ok, LangChain.Message.t()} | {:error, String.t()}

Convert the MessageDelta to a Message. Can only convert a fully complete MessageDelta.

This is assumed to be the result of merging all the received MessageDeltas. An error is returned if the status is :incomplete.

If the MessageDelta fails to convert to a LangChain.Message, an error is returned with the reason.