instructor_ex

Structured, Ecto outputs with OpenAI (and OSS LLMs)

---

Check out our Quickstart Guide to get up and running with Instructor in minutes.

Instructor provides structured prompting for LLMs. It is a spiritual port of the great Instructor Python Library by @jxnlco.

Instructor allows you to get structured output out of an LLM using Ecto.
You don't have to define any JSON schemas. You can just use Ecto as you've always used it.
And since it's just ecto, you can provide change set validations that you can use to ensure that what you're getting back from the LLM is not only properly structured, but semantically correct.

To learn more about the philosophy behind Instructor and its motivations, check out this Elixir Denver Meetup talk:

While Instructor is designed to be used with OpenAI, it also supports every major AI lab and open source LLM inference server:

• OpenAI
• Anthropic
• Groq
• Ollama
• Gemini
• vLLM
• llama.cpp

At its simplest, usage is pretty straightforward:

1. Create an ecto schema, with a @llm_doc string that explains the schema definition to the LLM.
2. Define a validate_changeset/1 function on the schema, and use the use Instructor macro in order for Instructor to know about it.
3. Make a call to Instructor.chat_completion/1 with an instruction for the LLM to execute.

You can use the max_retries parameter to automatically, iteratively go back and forth with the LLM to try fixing validation errorswhen they occur.

Mix.install([:instructor])

defmodule SpamPrediction do
  use Ecto.Schema
  use Validator

  @llm_doc """
  ## Field Descriptions:
  - class: Whether or not the email is spam.
  - reason: A short, less than 10 word rationalization for the classification.
  - score: A confidence score between 0.0 and 1.0 for the classification.
  """
  @primary_key false
  embedded_schema do
    field(:class, Ecto.Enum, values: [:spam, :not_spam])
    field(:reason, :string)
    field(:score, :float)
  end

  @impl true
  def validate_changeset(changeset) do
    changeset
    |> Ecto.Changeset.validate_number(:score,
      greater_than_or_equal_to: 0.0,
      less_than_or_equal_to: 1.0
    )
  end
end

is_spam? = fn text ->
  Instructor.chat_completion(
    model: "gpt-4o-mini",
    response_model: SpamPrediction,
    max_retries: 3,
    messages: [
      %{
        role: "user",
        content: """
        Your purpose is to classify customer support emails as either spam or not.
        This is for a clothing retail business.
        They sell all types of clothing.

        Classify the following email: 

        <email>
          #{text}
        </email>
        """
      }
    ]
  )
end

is_spam?.("Hello I am a Nigerian prince and I would like to send you money")

# => {:ok, %SpamPrediction{class: :spam, reason: "Nigerian prince email scam", score: 0.98}}

Installation

In your mix.exs,

def deps do
  [
    {:instructor, "~> 0.1.0"}
  ]
end