starlet/openai

OpenAI provider for starlet.

Uses the OpenAI Responses API for chat completions with support for server-side conversation continuation.

Usage

import starlet
import starlet/openai

let client = openai.new(api_key)

starlet.chat(client, "gpt-5-nano")
|> starlet.user("Hello!")
|> starlet.send()

Reasoning Models

For reasoning models (o1, o3, gpt-5), you can configure reasoning effort:

starlet.chat(client, "gpt-5-nano")
|> openai.with_reasoning(openai.ReasoningHigh)
|> starlet.user("Solve this step by step...")
|> starlet.send()

Types

Model

</>

Information about an available model.

pub type Model {
  Model(id: String, owned_by: String)
}

Constructors

```
Model(id: String, owned_by: String)
```

ReasoningEffort

</>

Reasoning effort level for OpenAI reasoning models.

pub type ReasoningEffort {
  ReasoningNone
  ReasoningLow
  ReasoningMedium
  ReasoningHigh
  ReasoningXHigh
}

Constructors

```
ReasoningNone
```
No reasoning tokens generated
```
ReasoningLow
```
Minimal reasoning, favors speed
```
ReasoningMedium
```
Balanced reasoning (default for reasoning models)
```
ReasoningHigh
```
Maximum reasoning depth
```
ReasoningXHigh
```
Extended high reasoning (GPT-5.2+)

Values

continue_from

</>

pub fn continue_from(
  chat: starlet.Chat(t, f, s, @internal Ext),
  id: String,
) -> starlet.Chat(t, f, s, @internal Ext)

Continue a conversation from a previous response ID. The server will use its stored conversation state.

list_models

</>

pub fn list_models(
  api_key: String,
) -> Result(List(Model), starlet.StarletError)

Lists available models from the OpenAI API.

list_models_with_base_url

</>

pub fn list_models_with_base_url(
  api_key: String,
  base_url: String,
) -> Result(List(Model), starlet.StarletError)

Lists available models from the OpenAI API with a custom base URL.

new

</>

pub fn new(api_key: String) -> starlet.Client(@internal Ext)

Creates a new OpenAI client with the given API key. Uses the default base URL: https://api.openai.com

new_with_base_url

</>

pub fn new_with_base_url(
  api_key: String,
  base_url: String,
) -> starlet.Client(@internal Ext)

Creates a new OpenAI client with a custom base URL. Useful for proxies or Azure OpenAI endpoints.

reasoning_summary

</>

pub fn reasoning_summary(
  turn: starlet.Turn(t, f, @internal Ext),
) -> option.Option(String)

Get the reasoning summary from an OpenAI turn (if present). Only available for reasoning models (o1, o3, gpt-5).

reset_response_id

</>

pub fn reset_response_id(
  chat: starlet.Chat(t, f, s, @internal Ext),
) -> starlet.Chat(t, f, s, @internal Ext)

Reset the response ID, disabling automatic conversation continuation. Use this to start a fresh conversation without the previous context.

response_id

</>

pub fn response_id(
  turn: starlet.Turn(t, f, @internal Ext),
) -> option.Option(String)

Get the response ID from an OpenAI turn.

with_reasoning

</>

pub fn with_reasoning(
  chat: starlet.Chat(t, f, s, @internal Ext),
  effort: ReasoningEffort,
) -> starlet.Chat(t, f, s, @internal Ext)

Set the reasoning effort for reasoning models (o1, o3, gpt-5). When not set, the provider’s default applies (medium for reasoning models).