# `InstructorLite`
[🔗](https://github.com/martosaur/instructor_lite/blob/v1.3.0/lib/instructor_lite.ex#L1)

Main building blocks of InstructorLite.

## Key Concepts

Structured prompting can be quite different depending on the LLM and InstructorLite does only the bare minimum to abstract this complexity. This means the usage can be quite different depending on the adapter you're using, so make sure to consult adapter documentation to learn the details.

There are two key arguments used throughout this module. Understanding what they are will make your life a lot easier.

* `params` - is an adapter-specific map, that contain values eventually sent to the LLM. More simply, this is the body that will be posted to the API endpoint. You prompt, model name, optional parameters like temperature all likely belong here.
* `opts` - is a list of options that shape behavior of InstructorLite itself. Options may include things like which schema to cast response to, http client to use, api key, optional headers, http timeout, etc.

## Shared options

Most functions in this module accept a list of options.
* `:response_model` - Required. A module implementing `InstructorLite.Instruction` behaviour, Ecto schema or [schemaless Ecto definition](https://hexdocs.pm/ecto/Ecto.Changeset.html#module-schemaless-changesets)

* `:max_retries` (`t:non_neg_integer/0`) - How many additional attempts to make if changeset validation fails. The default value is `0`.

* `:validate_changeset` (function of arity 2) - Override function to be called instead of `response_model.validate_changeset/2` callback

* `:notes` (`t:String.t/0`) - Additional notes about the schema that might be used by an adapter

* `:json_schema` (`t:map/0`) - JSON schema to use instead of calling response_model.json_schema/0 callback or generating it at runtime using `InstructorLite.JSONSchema` module

* `:adapter` (`t:atom/0`) - A module implementing `InstructorLite.Adapter` behaviour. The default value is `InstructorLite.Adapters.OpenAI`.

* `:adapter_context` (`t:term/0`) - Options used by adapter callbacks. See adapter docs for schema.

* `:extra` (`t:term/0`) - Any arbitrary term for ad-hoc usage. For example, in `c:InstructorLite.Instruction.validate_changeset/2` callback

# `ask_opts`

```elixir
@type ask_opts() :: [adapter: atom(), adapter_context: term(), extra: term()]
```

Ask options are a subset of all options, used by the `ask/2` function.

# `opts`

```elixir
@type opts() :: [
  response_model: atom() | Ecto.Changeset.types(),
  max_retries: non_neg_integer(),
  validate_changeset: (Ecto.Changeset.t(), opts() -> Ecto.Changeset.t()),
  notes: String.t(),
  json_schema: map(),
  adapter: atom(),
  adapter_context: term(),
  extra: term()
]
```

Options passed to instructor functions.

# `ask`
*since 1.1.0* 

```elixir
@spec ask(InstructorLite.Adapter.params(), ask_opts()) ::
  {:ok, String.t()} | {:error, any()} | {:error, atom(), any()}
```

Perform a simple request with a non-structured response.

This function is useful when you already have `InstructorLite` setup in the
project and need to get simple text output.

## Examples

### Basic Example

<!-- tabs-open -->

### OpenAI

```
iex> InstructorLite.ask(%{
    model: "gpt-5-mini-2025-08-07",
    input: [
      %{role: "user", content: "Cite me the greatest opening line in the history of cyberpunk."}
    ]
  },
  adapter: InstructorLite.Adapters.OpenAI,
  adapter_context: [api_key: Application.fetch_env!(:instructor_lite, :openai_key)]
)
{:ok, "The sky above the port was the color of television, tuned to a dead channel."}
```

### Anthropic

```
iex> InstructorLite.ask(%{
    messages: [
      %{role: "user", content: "Cite me the greatest opening line in the history of cyberpunk."}
    ],
    max_tokens: 100,
    model: "claude-sonnet-4-20250514"
  },
  adapter: InstructorLite.Adapters.Anthropic,
  adapter_context: [api_key: Application.fetch_env!(:instructor_lite, :anthropic_key)]
)
{:ok, "The sky above the port was the color of television, tuned to a dead channel."}
```

### Gemini

```elixir
iex> InstructorLite.ask(%{
    contents: [
      %{
        role: "user",
        parts: [%{text: "Cite me the greatest opening line in the history of cyberpunk."}]
      }
    ]
  },
  adapter: InstructorLite.Adapters.Gemini,
  adapter_context: [
    api_key: Application.fetch_env!(:instructor_lite, :gemini_key)
  ]
)
{:ok, "The sky above the port was the color of a bruise."} # 🫠
```

### Grok

```elixir
iex> InstructorLite.ask(%{
    model: "grok-3-latest",
    messages: [
      %{
        role: "user",
        content: "Cite me the greatest opening line in the history of cyberpunk."
      }
    ]
  },
  adapter: InstructorLite.Adapters.ChatCompletionsCompatible,
  adapter_context: [
    url: "https://api.x.ai/v1/chat/completions",
    api_key: Application.fetch_env!(:instructor_lite, :grok_key)
  ]
)
{:ok, "The sky above the port was the color of television, tuned to a dead channel."}
```

<!-- tabs-close -->

# `consume_response`

```elixir
@spec consume_response(
  InstructorLite.Adapter.response(),
  InstructorLite.Adapter.params(),
  opts()
) ::
  {:ok, Ecto.Schema.t()}
  | {:error, Ecto.Changeset.t(), InstructorLite.Adapter.params()}
  | {:error, any()}
  | {:error, reason :: atom(), any()}
```

Triage raw LLM response

Attempts to cast raw response from `c:InstructorLite.Adapter.send_request/2` and either returns an object or an invalid changeset with new prompt that can be used for a retry.

This function will call `c:InstructorLite.Instruction.validate_changeset/2` callback, unless `validate_changeset` option is overridden in `opts`.

# `instruct`

```elixir
@spec instruct(InstructorLite.Adapter.params(), opts()) ::
  {:ok, Ecto.Schema.t()}
  | {:error, Ecto.Changeset.t()}
  | {:error, any()}
  | {:error, atom(), any()}
```

Perform instruction session from start to finish.

This function glues together all other functions and adds retries on top.

## Examples

### Basic Example

<!-- tabs-open -->

### OpenAI

```
iex> InstructorLite.instruct(%{
    input: [
      %{role: "user", content: "John Doe is fourty two years old"}
    ]
  },
  response_model: %{name: :string, age: :integer},
  adapter: InstructorLite.Adapters.OpenAI,
  adapter_context: [api_key: Application.fetch_env!(:instructor_lite, :openai_key)]
)
{:ok, %{name: "John Doe", age: 42}}
```

### Anthropic

```
iex> InstructorLite.instruct(%{
    messages: [
      %{role: "user", content: "John Doe is fourty two years old"}
    ]
  },
  response_model: %{name: :string, age: :integer},
  adapter: InstructorLite.Adapters.Anthropic,
  adapter_context: [api_key: Application.fetch_env!(:instructor_lite, :anthropic_key)]
)
{:ok, %{name: "John Doe", age: 42}}
```

### Llamacpp

```
iex> InstructorLite.instruct(%{
    prompt: "John Doe is fourty two years old"
  },
  response_model: %{name: :string, age: :integer},
  adapter: InstructorLite.Adapters.Llamacpp,
  adapter_context: [url: Application.fetch_env!(:instructor_lite, :llamacpp_url)]
)
{:ok, %{name: "John Doe", age: 42}}
```

### Gemini

```elixir
iex> InstructorLite.instruct(%{
    contents: [
      %{
        role: "user",
        parts: [%{text: "John Doe is fourty two years old"}]
      }
    ]
  },
  response_model: %{name: :string, age: :integer},
  json_schema: %{
    type: "object",
    required: [:age, :name],
    properties: %{name: %{type: "string"}, age: %{type: "integer"}}
  },
  adapter: InstructorLite.Adapters.Gemini,
  adapter_context: [
    api_key: Application.fetch_env!(:instructor_lite, :gemini_key)
  ]
)
{:ok, %{name: "John Doe", age: 42}}
```

<!-- tabs-close -->

### Using `max_retries`

```
defmodule Rhymes do
  use Ecto.Schema
  use InstructorLite.Instruction
  
  @primary_key false
  embedded_schema do
    field(:word, :string)
    field(:rhymes, {:array, :string})
  end
  
  @impl true
  def validate_changeset(changeset, _opts) do
    Ecto.Changeset.validate_length(changeset, :rhymes, is: 3)
  end
end

InstructorLite.instruct(%{
    input: [
      %{role: "user", content: "Take the last word from the following line and add some rhymes to it
Even though you broke my heart"}
    ]
  },
  response_model: Rhymes,
  max_retries: 1,
  adapter_context: [api_key: Application.fetch_env!(:instructor_lite, :openai_key)]
)
{:ok, %Rhymes{word: "heart", rhymes: ["part", "start", "dart"]}}
```

# `prepare_prompt`

```elixir
@spec prepare_prompt(InstructorLite.Adapter.params(), opts()) ::
  InstructorLite.Adapter.params()
```

Prepare prompt that can be later sent to LLM

The prompt is added to `params`, so you need to cooperate with the adapter to know what you can provide there.

The function will call `c:InstructorLite.Instruction.notes/0` and `c:InstructorLite.Instruction.json_schema/0` callbacks for `response_model`. Both can be overriden with corresponding options in `opts`.

---

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