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

Collection of helpful utilities mostly for internal use.

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

```elixir
@type callback_data() ::
  LangChain.Message.t()
  | [LangChain.MessageDelta.t()]
  | LangChain.TokenUsage.t()
  | {:error, String.t()}
```

# `assign_string_value`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L421)

Changeset helper function for processing streamed text from an LLM.

A delta of " " a single empty space is expected. The "cast" process of the
changeset turns this into `nil` causing us to lose data.

We want to take whatever we are given here.

# `changeset_error_to_string`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L113)

```elixir
@spec changeset_error_to_string(Ecto.Changeset.t()) :: nil | String.t()
```

Return changeset errors as text with comma separated description.

# `conditionally_add_to_map`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L23)

```elixir
@spec conditionally_add_to_map(
  %{required(any()) => any()},
  key :: any(),
  value :: any()
) :: %{
  required(any()) => any()
}
```

Only add the key to the map if the value is present. When the value is a list,
the key will not be added when the list is empty. If the value is `nil`, it
will not be added.

# `extract_stream_error`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L287)

```elixir
@spec extract_stream_error(Req.Response.t()) :: {:ok, map()} | :not_found
```

Extract a structured error from a non-200 streaming response.

When `handle_stream_fn/3` processes error responses, it buffers the raw JSON
in the response's private `:error_buffer` key. This function attempts to
extract a parsed error map from either the response body (if already decoded)
or the buffered data.

Returns `{:ok, parsed_map}` with the decoded JSON map, or `:not_found`.

The caller is responsible for converting the parsed map into the appropriate
error struct (e.g. `LangChainError`), since the error structure varies by
provider.

# `fire_streamed_callback`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L152)

```elixir
@spec fire_streamed_callback(
  %{optional(:stream) => boolean(), callbacks: [map()]},
  data :: callback_data() | [callback_data()]
) :: :ok | no_return()
```

Fire a streaming callback if present.

# `handle_stream_fn`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L189)

```elixir
@spec handle_stream_fn(
  %{optional(:stream) => boolean()},
  decode_stream_fn :: function(),
  transform_data_fn :: function()
) :: function()
```

Creates and returns an anonymous function to handle the streaming response
from an API.

Accepts the following functions that handle the API-specific requirements:

- `decode_stream_fn` - a function that parses the raw results from an API. It
  deals with the specifics or oddities of a data source. The results come back
  as `{[list_of_parsed_json_maps], "incomplete text to buffer"}`. In some
  cases, a API may span the JSON data response across messages. This function
  assembles what is complete and returns any incomplete portion that is passed
  in on the next iteration of the function.

- `transform_data_fn` - a function that is executed to process the parsed
  JSON data in the form of an Elixir map into a LangChain struct of the
  appropriate type.

- `callback_fn` - a function that receives a successful result of from the
  `transform_data_fn`.

# `humanize_tool_name`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L502)

```elixir
@spec humanize_tool_name(String.t()) :: String.t()
```

Convert a tool name to a human-friendly display string.

## Examples

    iex> LangChain.Utils.humanize_tool_name("file_read")
    "File read"

    iex> LangChain.Utils.humanize_tool_name("search_web")
    "Search web"

# `migrate_to_content_parts`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L440)

```elixir
@spec migrate_to_content_parts(Ecto.Changeset.t()) :: Ecto.Changeset.t()
```

Migrate a string content to use `LangChain.Message.ContentPart`. This is for
backward compatibility with models that don't yet support ContentPart while
providing a more consistent API.

This can be used with Message contents and ToolResult contents.

# `module_from_name`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L372)

Return an `{:ok, module}` when the string successfully converts to an existing
module.

# `put_in_list`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L310)

```elixir
@spec put_in_list([any()], integer(), any()) :: [any()]
```

Put the value in the list at the desired index. If the index does not exist,
return an updated list where it now exists with the value in that index.

# `replace_system_message!`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L407)

```elixir
@spec replace_system_message!([LangChain.Message.t()], LangChain.Message.t()) ::
  [LangChain.Message.t()] | no_return()
```

Replace the system message with a new system message. This retains all other
messages as-is. An error is raised if there are more than 1 system messages.

# `split_system_message`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L392)

```elixir
@spec split_system_message([LangChain.Message.t()], error_message :: String.t()) ::
  {nil | LangChain.Message.t(), [LangChain.Message.t()]} | no_return()
```

Split the messages into "system" and "other".
Raises an error with the specified error message if more than 1 system message present.
Returns a tuple with the single system message and the list of other messages.

# `stringify_keys`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L339)

Convert map atom keys to strings

Original source: https://gist.github.com/kipcole9/0bd4c6fb6109bfec9955f785087f53fb

# `to_serializable_map`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L325)

```elixir
@spec to_serializable_map(struct(), keys :: [atom()], version :: integer()) :: %{
  required(String.t()) => any()
}
```

Given a struct, create a map with the selected keys converted to strings.
Additionally includes a `version` number for the data.

# `translate_error`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L84)

Translates an error message using gettext.

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

Translates the errors for a field from a keyword list of errors.

# `validate_llm_is_struct`
[🔗](https://github.com/brainlid/langchain/blob/v0.8.0/lib/utils.ex#L134)

```elixir
@spec validate_llm_is_struct(Ecto.Changeset.t()) :: Ecto.Changeset.t()
```

Validation helper. Validates a struct changeset that the LLM is a struct.

---

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