Casts all the parameters in the params map to the types defined in the types map. This works both with Ecto Schemas and maps of Ecto types (see Schemaless Ecto).

Examples

When using a full Ecto Schema

iex> Instructor.cast_all(%{
...>   data: %Instructor.Demos.SpamPrediction{},
...>   types: %{
...>     class: :string,
...>     score: :float
...>   }
...> }, %{
...>   class: "spam",
...>   score: 0.999
...> })
%Ecto.Changeset{
  action: nil,
  changes: %{
    class: "spam",
    score: 0.999
  },
  errors: [],
  data: %Instructor.Demos.SpamPrediction{
    class: :spam,
    score: 0.999
  },
  valid?: true
}copy

When using a map of Ecto types

iex> Instructor.cast_all(%Instructor.Demo.SpamPrediction{}, %{
...>   class: "spam",
...>   score: 0.999
...> })
%Ecto.Changeset{
  action: nil,
  changes: %{
    class: "spam",
    score: 0.999
  },
  errors: [],
  data: %{
    class: :spam,
    score: 0.999
  },
  valid?: true
}copy

and when using raw Ecto types,

iex> Instructor.cast_all({%{},%{name: :string}, %{
...>   name: "George Washington"
...> })
%Ecto.Changeset{
  action: nil,
  changes: %{
    name: "George Washington",
  },
  errors: [],
  data: %{
    name: "George Washington",
  },
  valid?: true
}copy

@spec chat_completion(Keyword.t(), any()) ::
  {:ok, Ecto.Schema.t()}
  | {:error, Ecto.Changeset.t()}
  | {:error, String.t()}
  | stream()

Create a new chat completion for the provided messages and parameters.

The parameters are passed directly to the LLM adapter. By default they shadow the OpenAI API parameters. For more information on the parameters, see the OpenAI API docs.

Additionally, the following parameters are supported:

• :adapter - The adapter to use for chat completion. (defaults to the configured adapter, which defaults to Instructor.Adapters.OpenAI)
• :response_model - The Ecto schema to validate the response against, or a valid map of Ecto types (see Schemaless Ecto).
• :stream - Whether to stream the response or not. (defaults to false)
• :validation_context - The validation context to use when validating the response. (defaults to %{})
• :mode - The mode to use when parsing the response, :tools, :json, :md_json (defaults to :tools), generally speaking you don't need to change this unless you are not using OpenAI.
• :max_retries - The maximum number of times to retry the LLM call if it fails, or does not pass validations.

               (defaults to `0`)copy

Examples

iex> Instructor.chat_completion(
...>   model: "gpt-4o-mini",
...>   response_model: Instructor.Demos.SpamPrediction,
...>   messages: [
...>     %{
...>       role: "user",
...>       content: "Classify the following text: Hello, I am a Nigerian prince and I would like to give you $1,000,000."
...>     }
...>   ])
{:ok,
    %Instructor.Demos.SpamPrediction{
        class: :spam
        score: 0.999
    }}copy

When you're using Instructor in Streaming Mode, instead of returning back a tuple, it will return back a stream that emits tuples. There are two main streaming modes available. array streaming and partial streaming.

Partial streaming will emit the record multiple times until it's complete.

iex> Instructor.chat_completion(
...>   model: "gpt-4o-mini",
...>   response_model: {:partial, %{name: :string, birth_date: :date}}
...>   messages: [
...>     %{
...>       role: "user",
...>       content: "Who is the first president of the United States?"
...>     }
...>   ]) |> Enum.to_list()
[
  {:partial, %{name: "George Washington"}},
  {:partial, %{name: "George Washington", birth_date: ~D[1732-02-22]}},
  {:ok, %{name: "George Washington", birth_date: ~D[1732-02-22]}}
]copy

Whereas with array streaming, you can ask the LLM to return multiple instances of your Ecto schema, and instructor will emit them one at a time as they arrive in complete form and validated.

iex> Instructor.chat_completion(
...>   model: "gpt-4o-mini",
...>   response_model: {:array, %{name: :string, birth_date: :date}}
...>   messages: [
...>     %{
...>       role: "user",
...>       content: "Who are the first 5 presidents of the United States?"
...>     }
...>   ]) |> Enum.to_list()

[
  {:ok, %{name: "George Washington", birth_date: ~D[1732-02-22]}},
  {:ok, %{name: "John Adams", birth_date: ~D[1735-10-30]}},
  {:ok, %{name: "Thomas Jefferson", birth_date: ~D[1743-04-13]}},
  {:ok, %{name: "James Madison", birth_date: ~D[1751-03-16]}},
  {:ok, %{name: "James Monroe", birth_date: ~D[1758-04-28]}}
]copy

If there's a validation error, it will return an error tuple with the change set describing the errors.

iex> Instructor.chat_completion(
...>   model: "gpt-4o-mini",
...>   response_model: Instructor.Demos.SpamPrediction,
...>   messages: [
...>     %{
...>       role: "user",
...>       content: "Classify the following text: Hello, I am a Nigerian prince and I would like to give you $1,000,000."
...>     }
...>   ])
{:error,
    %Ecto.Changeset{
        changes: %{
            class: "foobar",
            score: -10.999
        },
        errors: [
            class: {"is invalid", [type: :string, validation: :cast]}
        ],
        valid?: false
    }}copy