### Install Starlet using Gleam

Source: https://hexdocs.pm/starlet/index

This snippet shows how to add the Starlet library to your Gleam project using the `gleam add` command. Ensure you have Gleam installed and a project initialized.

```bash
gleam add starlet

```

--------------------------------

### Multi-turn Conversation Example with Starlet

Source: https://hexdocs.pm/starlet/index

Illustrates how to manage multi-turn conversations using Starlet. This example chains user messages and processes the responses sequentially, accumulating the conversation history for context.

```gleam
import gleam/result
import starlet
import starlet/ollama

pub fn main() {
  let client = ollama.new("http://localhost:11434")

  let result = {
    let chat = 
      starlet.chat(client, "gpt-oss:20b")
      |> starlet.user("Hello!")

    use #(chat, _turn) <- result.try(starlet.send(chat))

    let chat = starlet.user(chat, "How are you?")
    use #(_chat, turn) <- result.try(starlet.send(chat))

    Ok(starlet.text(turn))
  }

  // result contains the final response or first error
}

```

--------------------------------

### Quick Start: Initialize and Chat with Starlet

Source: https://hexdocs.pm/starlet/starlet

Demonstrates how to initialize a Starlet client for the Ollama provider and initiate a chat conversation. It shows setting a system prompt, adding a user message, sending the message, and handling the response or errors.

```elixir
import starlet
import starlet/ollama

let client = ollama.new("http://localhost:11434")

let chat =
  starlet.chat(client, "qwen3:0.6b")
  |> starlet.system("You are a helpful assistant.")
  |> starlet.user("Hello!")

case starlet.send(chat) {
  Ok(#(new_chat, turn)) -> starlet.text(turn)
  Error(err) -> // handle error
}

```

--------------------------------

### Initialize and Use Gemini Chat Client

Source: https://hexdocs.pm/starlet/starlet/gemini

Demonstrates how to initialize a Gemini client with an API key and perform a basic chat interaction using the Starlet framework. This is the fundamental way to start a conversation with a Gemini model.

```nim
import starlet
import starlet/gemini

let client = gemini.new(api_key)

starlet.chat(client, "gemini-2.5-flash")
|> starlet.user("Hello!")
|> starlet.send()
```

--------------------------------

### Quick Start: Basic Chat with Ollama using Starlet

Source: https://hexdocs.pm/starlet/index

Demonstrates a basic chat interaction using Starlet and the Ollama provider. It initializes an Ollama client, sets a system prompt, sends a user message, and prints the assistant's response. Error handling is included.

```gleam
import gleam/io
import gleam/result
import starlet
import starlet/ollama

pub fn main() {
  let client = ollama.new("http://localhost:11434")

  let chat = 
    starlet.chat(client, "gpt-oss:20b")
    |> starlet.system("You are a helpful assistant.")
    |> starlet.user("What is the capital of France?")

  case starlet.send(chat) {
    Ok(#(_chat, turn)) -> io.println(starlet.text(turn))
    Error(_) -> io.println("Request failed")
  }
}

```

--------------------------------

### GET /tools

Source: https://hexdocs.pm/starlet/starlet

Get the tool definitions from a tools-enabled chat.

```APIDOC
## GET /tools

### Description
Get the tool definitions from a tools-enabled chat.

### Method
GET

### Endpoint
/tools

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat** (Chat) - Required - The tools-enabled chat object.

### Request Example
```json
{
  "chat": { ... } // Assumes chat is in ToolsOn state
}
```

### Response
#### Success Response (200)
- **tools** (List[tool.Definition]) - A list of tool definitions.

#### Response Example
```json
{
  "tools": [
    { "name": "tool1", "description": "...", "parameters": { ... } },
    { "name": "tool2", "description": "...", "parameters": { ... } }
  ]
}
```
```

--------------------------------

### Tool Calling with Starlet and Ollama

Source: https://hexdocs.pm/starlet/index

This example demonstrates how to enable tool calling with Starlet. It defines a 'get_weather' tool, sets up a dispatcher to handle tool execution, and integrates it into the chat flow. It uses `starlet.step` and `starlet.apply_tool_results` to manage the tool call lifecycle.

```gleam
import gleam/dynamic/decode
import gleam/json
import gleam/result
import starlet
import starlet/ollama
import starlet/tool

pub fn main() {
  let client = ollama.new("http://localhost:11434")

  // Define a tool
  let weather_tool = 
    tool.function(
      name: "get_weather",
      description: "Get weather for a city",
      parameters: json.object([
        #("type", json.string("object")),
        #("properties", json.object([
          #("city", json.object([#("type", json.string("string"))])),
        ])),
      ]),
    )

  // Decoder for the tool arguments
  let city_decoder = {
    use city <- decode.field("city", decode.string)
    decode.success(city)
  }

  // Create a handler that executes tools
  let dispatcher = 
    tool.dispatch([
      tool.handler("get_weather", city_decoder, fn(city) {
        let temp = case city {
          "Tokyo" -> 18
          "Paris" -> 22
          _ -> 20
        }
        Ok(json.object([
          #("temp", json.int(temp)),
          #("condition", json.string("sunny")),
        ]))
      }),
    ])

  let chat = 
    starlet.chat(client, "gpt-oss:20b")
    |> starlet.with_tools([weather_tool])
    |> starlet.user("What's the weather in Tokyo?")

  // Use step/apply_tool_results loop to handle tool calls
  use step <- result.try(starlet.step(chat))
  case step {
    starlet.ToolCall(chat:, calls:, ..) -> {
      use chat <- result.try(starlet.apply_tool_results(chat, calls, dispatcher))
      starlet.send(chat)  // Continue after tools execute
    }
    starlet.Done(..) -> Ok(step)
  }
}

```

--------------------------------

### Reasoning (Extended Thinking) with Starlet and Ollama

Source: https://hexdocs.pm/starlet/index

This example shows how to enable and access the model's 'thinking' process, often referred to as 'extended thinking' or 'reasoning' steps, when using the Ollama provider with Starlet. It demonstrates how to toggle this feature and access the thinking output if available.

```gleam
import gleam/option.{None, Some}
import gleam/result
import starlet
import starlet/ollama

pub fn main() {
  let client = ollama.new("http://localhost:11434")

  let chat = 
    starlet.chat(client, "gpt-oss:20b")
    |> ollama.with_thinking(True)
    |> starlet.user("What is the sum of primes between 1 and 20?")

  use #(_chat, turn) <- result.try(starlet.send(chat))

  // Access thinking content (provider-specific)
  case ollama.thinking(turn) {
    Some(thinking) -> // The model's thinking process
    None -> // No thinking available
  }

  starlet.text(turn)  // The final answer
}

```

--------------------------------

### Structured JSON Output with Starlet

Source: https://hexdocs.pm/starlet/index

This example shows how to configure Starlet to expect structured JSON output from the LLM. It defines a `Person` type and a corresponding decoder, specifies a JSON schema for the output, and then parses the LLM's response into the defined type.

```gleam
import gleam/dynamic/decode
import gleam/json
import gleam/result
import jscheam/schema
import starlet
import starlet/ollama

// Define your output type
pub type Person {
  Person(name: String, age: Int)
}

// Create a decoder for the type
fn person_decoder() -> decode.Decoder(Person) {
  use name <- decode.field("name", decode.string)
  use age <- decode.field("age", decode.int)
  decode.success(Person(name:, age:))
}

pub fn main() {
  let client = ollama.new("http://localhost:11434")

  // Define the output schema (must match your type)
  let person_schema = 
    schema.object([
      schema.prop("name", schema.string()),
      schema.prop("age", schema.integer()),
    ])

  let chat = 
    starlet.chat(client, "gpt-oss:20b")
    |> starlet.with_json_output(person_schema)
    |> starlet.user("Extract: Alice is 30 years old.")

  use #(_chat, turn) <- result.try(starlet.send(chat))

  // Get the JSON string
  let json_string = starlet.json(turn)

  // Parse and decode into your type
  case json.parse(json_string, person_decoder()) {
    Ok(person) -> // person.name == "Alice", person.age == 30
    Error(_) -> // Handle decode error
  }
}

```

--------------------------------

### Get Tool Definitions from Chat

Source: https://hexdocs.pm/starlet/starlet

Retrieves the list of tool definitions associated with a chat session that has tools enabled.

```Rust
pub fn tools(
  chat: Chat(@internal ToolsOn, format, state, ext),
) -> List(tool.Definition)

```

--------------------------------

### Get Provider Name

Source: https://hexdocs.pm/starlet/starlet

Retrieves the name of the language model provider, such as 'ollama' or 'openai'.

```Rust
pub fn provider_name(client: Client(ext)) -> String

```

--------------------------------

### POST /assistant

Source: https://hexdocs.pm/starlet/starlet

Adds an assistant message to the chat history. Useful for providing few-shot examples or resuming a conversation. Requires the chat to already have a user message.

```APIDOC
## POST /assistant

### Description
Adds an assistant message to the chat history. Useful for providing few-shot examples or resuming a conversation. Requires the chat to already have a user message.

### Method
POST

### Endpoint
/assistant

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat** (Chat) - Required - The current chat object.
- **text** (String) - Required - The assistant's message content.

### Request Example
```json
{
  "chat": { ... },
  "text": "This is a follow-up from the assistant."
}
```

### Response
#### Success Response (200)
- **chat** (Chat) - The updated chat object with the assistant message added.

#### Response Example
```json
{
  "chat": { ... }
}
```
```

--------------------------------

### GET /provider_name

Source: https://hexdocs.pm/starlet/starlet

Returns the name of the provider (e.g., “ollama”, “openai”).

```APIDOC
## GET /provider_name

### Description
Returns the name of the provider (e.g., “ollama”, “openai”).

### Method
GET

### Endpoint
/provider_name

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **client** (Client) - Required - The client object whose provider name is to be retrieved.

### Request Example
```json
{
  "client": { ... }
}
```

### Response
#### Success Response (200)
- **provider_name** (String) - The name of the provider.

#### Response Example
```json
{
  "provider_name": "ollama"
}
```
```

--------------------------------

### GET /timeout

Source: https://hexdocs.pm/starlet/starlet

Returns the current timeout in milliseconds.

```APIDOC
## GET /timeout

### Description
Returns the current timeout in milliseconds.

### Method
GET

### Endpoint
/timeout

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat** (Chat) - Required - The chat object whose timeout is to be retrieved.

### Request Example
```json
{
  "chat": { ... }
}
```

### Response
#### Success Response (200)
- **timeout_ms** (Int) - The current timeout value in milliseconds.

#### Response Example
```json
{
  "timeout_ms": 60000
}
```
```

--------------------------------

### Manage Conversation Continuation

Source: https://hexdocs.pm/starlet/starlet/openai

Allows continuing a conversation from a previous response ID, leveraging server-side state. It also provides functionality to reset the response ID to start a fresh conversation.

```elixir
# Continue conversation
let new_chat = openai.continue_from(previous_chat, response_id)

# Reset conversation context
let fresh_chat = openai.reset_response_id(previous_chat)
```

--------------------------------

### Get Current Timeout Setting

Source: https://hexdocs.pm/starlet/starlet

Retrieves the current HTTP request timeout value in milliseconds.

```Rust
pub fn timeout(
  chat: Chat(tools_state, format, state, ext),
) -> Int

```

--------------------------------

### Send Chat to LLM and Get Response

Source: https://hexdocs.pm/starlet/starlet

Transmits the current chat to the language model and returns the response. It yields a tuple containing the updated chat object and the turn with the response details. Error handling for the response is included.

```Rust
pub fn send(
  chat: Chat(tools_state, format, @internal Ready, ext),
) -> Result(
  #(
    Chat(tools_state, format, @internal Ready, ext),
    Turn(tools_state, format, ext),
  ),
  StarletError,
)

```

```Rust
case starlet.send(chat) {
  Ok(#(new_chat, turn)) -> starlet.text(turn)
  Error(err) -> // handle error
}

```

--------------------------------

### Add Assistant Message to Chat

Source: https://hexdocs.pm/starlet/starlet

Appends an assistant message to the chat history. This function is useful for providing few-shot examples or resuming conversations and requires an existing user message in the chat.

```Rust
pub fn assistant(
  chat: Chat(tools_state, format, @internal Ready, ext),
  text: String,
) -> Chat(tools_state, format, @internal Ready, ext)

```

--------------------------------

### Reasoning Models and Configuration

Source: https://hexdocs.pm/starlet/starlet/openai

This section explains how to use reasoning models and configure their effort levels for more detailed analysis.

```APIDOC
## POST /openai/with_reasoning

### Description
Configures the reasoning effort for reasoning models (o1, o3, gpt-5).

### Method
POST

### Endpoint
/openai/with_reasoning

### Parameters
#### Request Body
- **chat** (starlet.Chat) - Required - The current chat object.
- **effort** (ReasoningEffort) - Required - The desired reasoning effort level (ReasoningNone, ReasoningLow, ReasoningMedium, ReasoningHigh, ReasoningXHigh).

### Request Example
```json
{
  "chat": "<chat_object>",
  "effort": "ReasoningHigh"
}
```

### Response
#### Success Response (200)
- **updated_chat** (starlet.Chat) - The chat object with the reasoning effort configured.

#### Response Example
```json
{
  "updated_chat": "<updated_chat_object>"
}
```

## GET /openai/reasoning_summary

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

### Method
GET

### Endpoint
/openai/reasoning_summary

### Parameters
#### Query Parameters
- **turn** (starlet.Turn) - Required - The turn object to extract the reasoning summary from.

### Request Example
```json
{
  "turn": "<turn_object>"
}
```

### Response
#### Success Response (200)
- **summary** (Option[String]) - An optional string containing the reasoning summary.

#### Response Example
```json
{
  "summary": "The model followed these steps..."
}
```

## GET /openai/response_id

### Description
Gets the response ID from an OpenAI turn.

### Method
GET

### Endpoint
/openai/response_id

### Parameters
#### Query Parameters
- **turn** (starlet.Turn) - Required - The turn object to extract the response ID from.

### Request Example
```json
{
  "turn": "<turn_object>"
}
```

### Response
#### Success Response (200)
- **response_id** (Option[String]) - An optional string containing the response ID.

#### Response Example
```json
{
  "response_id": "resp_12345abc"
}
```
```

--------------------------------

### OpenAI Provider Initialization

Source: https://hexdocs.pm/starlet/starlet/openai

This section covers how to create a new OpenAI client using your API key, with options for specifying a custom base URL.

```APIDOC
## POST /openai/new

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

### Method
POST

### Endpoint
/openai/new

### Parameters
#### Query Parameters
- **api_key** (String) - Required - Your OpenAI API key.

### Request Example
```json
{
  "api_key": "YOUR_API_KEY"
}
```

### Response
#### Success Response (200)
- **client** (starlet.Client) - The initialized OpenAI client.

#### Response Example
```json
{
  "client": "<client_object>"
}
```

## POST /openai/new_with_base_url

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

### Method
POST

### Endpoint
/openai/new_with_base_url

### Parameters
#### Query Parameters
- **api_key** (String) - Required - Your OpenAI API key.
- **base_url** (String) - Required - The custom base URL for the OpenAI API.

### Request Example
```json
{
  "api_key": "YOUR_API_KEY",
  "base_url": "YOUR_CUSTOM_BASE_URL"
}
```

### Response
#### Success Response (200)
- **client** (starlet.Client) - The initialized OpenAI client.

#### Response Example
```json
{
  "client": "<client_object>"
}
```
```

--------------------------------

### Enable Tools on Chat (Rust)

Source: https://hexdocs.pm/starlet/starlet

The `with_tools` function enables a list of tool definitions on a chat. It transitions the chat state from `ToolsOff` to `ToolsOn`. This function is essential for preparing a chat to utilize external tools.

```rust
pub fn with_tools(
  chat: Chat(@internal ToolsOff, format, state, ext),
  tool_defs: List(tool.Definition),
) -> Chat(@internal ToolsOn, format, state, ext)

```

--------------------------------

### Ollama Client Initialization

Source: https://hexdocs.pm/starlet/starlet/ollama

Shows how to create a new Ollama client instance.

```APIDOC
## POST /websites/hexdocs_pm_starlet/ollama/new

### Description
Initializes a new Ollama client instance, establishing a connection to the Ollama server.

### Method
POST (Implicitly through Starlet's client creation)

### Endpoint
(Not a direct HTTP endpoint, but part of the Ollama provider functionality)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```starlet
let client = ollama.new("http://localhost:11434")
```

### Response
#### Success Response (200)
(A Starlet Client object configured for Ollama)

#### Response Example
(The response is a `starlet.Client` object)

```

--------------------------------

### Create New Gemini Client

Source: https://hexdocs.pm/starlet/starlet/gemini

Function to create a new Gemini client instance using an API key. It utilizes the default Google AI Studio base URL and returns a Starlet client object.

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

--------------------------------

### Create a Typed Tool Handler

Source: https://hexdocs.pm/starlet/starlet/tool

Demonstrates creating a tool handler that automatically decodes arguments to a specified type. It uses `tool.handler` with a custom decoder for the 'city' argument and a run function that returns a string indicating the weather.

```gleam
let decoder = {
  use city <- decode.field("city", decode.string)
  decode.success(city)
}

let #(name, run) =
  tool.handler("get_weather", decoder, fn(city) {
    Ok(json.string("Weather in " <> city))
  })

```

--------------------------------

### Create New Chat Session

Source: https://hexdocs.pm/starlet/starlet

Initializes a new chat session with a specified client and model name. The chat inherits the provider's extension type from the client, enabling configuration of provider-specific features.

```Rust
pub fn chat(
  client: Client(ext),
  model: String,
) -> Chat(
  @internal ToolsOff,
  @internal FreeText,
  @internal Empty,
  ext,
)

```

```Rust
let chat = starlet.chat(client, "qwen3:0.6b")

```

--------------------------------

### Initialize OpenAI Client

Source: https://hexdocs.pm/starlet/starlet/openai

Creates a new OpenAI client for starlet using an API key. It can use a default or custom base URL, useful for proxies or Azure OpenAI endpoints.

```elixir
let client = openai.new(api_key)

let client = openai.new_with_base_url(api_key, "https://your.custom.url")
```

--------------------------------

### Handle Tool Calls with Argument Decoding

Source: https://hexdocs.pm/starlet/starlet/tool

Sets up a tool dispatcher that handles calls to the 'get_weather' tool. It includes a decoder for the 'city' argument and a handler function that returns a temperature based on the city. This demonstrates automatic argument decoding for tool handlers.

```gleam
let city_decoder = {
  use city <- decode.field("city", decode.string)
  decode.success(city)
}

let dispatcher = tool.dispatch([
  tool.handler("get_weather", city_decoder, fn(city) {
    let temp = case city {
      "Tokyo" -> 18
      _ -> 22
    }
    Ok(json.object([#("temp", json.int(temp))]))
  }),
])

```

--------------------------------

### Create Gemini Client with Custom Base URL

Source: https://hexdocs.pm/starlet/starlet/gemini

Allows the creation of a Gemini client with a custom base URL, providing flexibility for different deployment scenarios or network configurations.

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

--------------------------------

### PUT /system

Source: https://hexdocs.pm/starlet/starlet

Sets the system prompt for the chat. Must be called before adding any user messages.

```APIDOC
## PUT /system

### Description
Sets the system prompt for the chat. Must be called before adding any user messages.

### Method
PUT

### Endpoint
/system

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat** (Chat) - Required - The chat object to configure.
- **text** (String) - Required - The system prompt text.

### Request Example
```json
{
  "chat": { ... },
  "text": "You are a helpful assistant."
}
```

### Response
#### Success Response (200)
- **chat** (Chat) - The updated chat object with the system prompt set.

#### Response Example
```json
{
  "chat": { ... }
}
```
```

--------------------------------

### PUT /with_json_output

Source: https://hexdocs.pm/starlet/starlet

Enable JSON output with a schema. Transitions FreeText → JsonFormat. The model will be constrained to output valid JSON matching the schema. Use `json(turn)` to extract the JSON string from the response.

```APIDOC
## PUT /with_json_output

### Description
Enable JSON output with a schema. Transitions FreeText → JsonFormat. The model will be constrained to output valid JSON matching the schema. Use `json(turn)` to extract the JSON string from the response.

### Method
PUT

### Endpoint
/with_json_output

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat** (Chat) - Required - The chat object configured for free text output.
- **output_schema** (schema.Type) - Required - The JSON schema for the output.

### Request Example
```json
{
  "chat": { ... }, // Assumes chat is in FreeText format
  "output_schema": {
    "type": "object",
    "properties": {
      "key": { "type": "string" }
    }
  }
}
```

### Response
#### Success Response (200)
- **chat** (Chat) - The updated chat object now configured for JSON output.

#### Response Example
```json
{
  "chat": { ... } // Now in JsonFormat
}
```
```

--------------------------------

### Chat Completion with Reasoning Effort

Source: https://hexdocs.pm/starlet/starlet/openai

Configures chat completions for reasoning models (o1, o3, gpt-5) with specific reasoning effort levels. This allows for fine-tuning the model's reasoning capabilities.

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

--------------------------------

### POST /tool_calls

Source: https://hexdocs.pm/starlet/starlet

Extract tool calls from a turn. Only available when tools are enabled.

```APIDOC
## POST /tool_calls

### Description
Extract tool calls from a turn. Only available when tools are enabled.

### Method
POST

### Endpoint
/tool_calls

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **turn** (Turn) - Required - The turn object from which to extract tool calls.

### Request Example
```json
{
  "turn": { ... } // Assumes turn is in ToolsOn state
}
```

### Response
#### Success Response (200)
- **calls** (List[tool.Call]) - A list of tool calls found in the turn.

#### Response Example
```json
{
  "calls": [
    { "name": "tool1", "args": { ... } },
    { "name": "tool2", "args": { ... } }
  ]
}
```
```

--------------------------------

### POST /user

Source: https://hexdocs.pm/starlet/starlet

Adds a user message to the chat. This transitions the chat to the `Ready` state, allowing it to be sent.

```APIDOC
## POST /user

### Description
Adds a user message to the chat. This transitions the chat to the `Ready` state, allowing it to be sent.

### Method
POST

### Endpoint
/user

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat** (Chat) - Required - The chat object to add the message to.
- **text** (String) - Required - The user's message content.

### Request Example
```json
{
  "chat": { ... },
  "text": "Hello, how are you?"
}
```

### Response
#### Success Response (200)
- **chat** (Chat) - The updated chat object with the user message added, now in `Ready` state.

#### Response Example
```json
{
  "chat": { ... } // Now in Ready state
}
```
```

--------------------------------

### Set System Prompt for Chat

Source: https://hexdocs.pm/starlet/starlet

Establishes the system prompt for the chat session. This function must be invoked before any user messages are added to the chat.

```Rust
pub fn system(
  chat: Chat(tools, format, @internal Empty, ext),
  text: String,
) -> Chat(tools, format, @internal Empty, ext)

```

--------------------------------

### Apply Tool Results to Chat (Rust)

Source: https://hexdocs.pm/starlet/starlet

The `with_tool_results` function applies pre-computed tool results to a chat. This function should be used when the tools have already been executed externally. It takes the current chat state and a list of tool results, returning the updated chat state with the results incorporated.

```rust
pub fn with_tool_results(
  chat: Chat(@internal ToolsOn, format, @internal Ready, ext),
  results: List(tool.ToolResult),
) -> Chat(@internal ToolsOn, format, @internal Ready, ext)

```

--------------------------------

### Process Tools-Enabled Chat Turn

Source: https://hexdocs.pm/starlet/starlet

Sends a chat session configured for tools and categorizes the response. It returns either 'Done' if no tool calls are made or 'ToolCall' if tools are requested by the model.

```Rust
pub fn step(
  chat: Chat(@internal ToolsOn, format, @internal Ready, ext),
) -> Result(Step(format, ext), StarletError)

```

--------------------------------

### Ollama Provider Integration

Source: https://hexdocs.pm/starlet/starlet/ollama

Demonstrates how to initialize the Ollama client and send a basic chat message using the Starlet library.

```APIDOC
## POST /websites/hexdocs_pm_starlet/ollama

### Description
This section outlines the usage of the Ollama provider within the Starlet framework. It covers initializing a client and sending chat messages to Ollama-hosted models.

### Method
POST (Implicitly through Starlet's chat functions)

### Endpoint
(Not a direct HTTP endpoint, but integrates with Starlet's client)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(Managed internally by Starlet's client and message formatting)

### Request Example
```starlet
import starlet
import starlet/ollama

let client = ollama.new("http://localhost:11434")

starlet.chat(client, "qwen3:0.6b")
|> starlet.user("Hello!")
|> starlet.send()
```

### Response
#### Success Response (200)
(A Starlet Turn object containing the model's response)

#### Response Example
(Example response structure depends on the Starlet Turn object and model output)

```

--------------------------------

### POST /has_tool_calls

Source: https://hexdocs.pm/starlet/starlet

Check if a turn has any tool calls.

```APIDOC
## POST /has_tool_calls

### Description
Check if a turn has any tool calls.

### Method
POST

### Endpoint
/has_tool_calls

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **turn** (Turn) - Required - The turn object to check.

### Request Example
```json
{
  "turn": { ... }
}
```

### Response
#### Success Response (200)
- **result** (Bool) - True if the turn has tool calls, false otherwise.

#### Response Example
```json
{
  "result": true
}
```
```

--------------------------------

### POST /step

Source: https://hexdocs.pm/starlet/starlet

Send a tools-enabled chat and categorize the response. Returns either Done (no tool calls) or ToolCall (tools requested).

```APIDOC
## POST /step

### Description
Send a tools-enabled chat and categorize the response. Returns either Done (no tool calls) or ToolCall (tools requested).

### Method
POST

### Endpoint
/step

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat** (Chat) - Required - The tools-enabled chat object.

### Request Example
```json
{
  "chat": { ... } // Assumes chat is in ToolsOn state and Ready
}
```

### Response
#### Success Response (200)
- **result** (Step) - The result of the step, either Done or ToolCall.

#### Response Example
```json
{
  "result": {
    "type": "ToolCall",
    "calls": [ ... ]
  }
}
```
```

--------------------------------

### PUT /with_free_text

Source: https://hexdocs.pm/starlet/starlet

Disable JSON output, return to free text. Transitions JsonFormat → FreeText.

```APIDOC
## PUT /with_free_text

### Description
Disable JSON output, return to free text. Transitions JsonFormat → FreeText.

### Method
PUT

### Endpoint
/with_free_text

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat** (Chat) - Required - The chat object configured for JSON output.

### Request Example
```json
{
  "chat": { ... } // Assumes chat is in JsonFormat
}
```

### Response
#### Success Response (200)
- **chat** (Chat) - The updated chat object now configured for free text output.

#### Response Example
```json
{
  "chat": { ... } // Now in FreeText format
}
```
```

--------------------------------

### POST /text

Source: https://hexdocs.pm/starlet/starlet

Extracts the text content from a turn. Only available for free text format turns.

```APIDOC
## POST /text

### Description
Extracts the text content from a turn. Only available for free text format turns.

### Method
POST

### Endpoint
/text

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **turn** (Turn) - Required - The turn object from which to extract text.

### Request Example
```json
{
  "turn": { ... } // Assumes turn is in FreeText format
}
```

### Response
#### Success Response (200)
- **content** (String) - The extracted text content.

#### Response Example
```json
{
  "content": "This is the response text."
}
```
```

--------------------------------

### List Available OpenAI Models

Source: https://hexdocs.pm/starlet/starlet/openai

Retrieves a list of available models from the OpenAI API. It can be used with the default or a custom base URL.

```elixir
openai.list_models(api_key)
openai.list_models_with_base_url(api_key, "https://your.custom.url")
```

--------------------------------

### Apply Tool Results Function

Source: https://hexdocs.pm/starlet/starlet

Provides the `apply_tool_results` function, which takes a chat, tool calls, and a runner function. It executes the tools and applies their results to the chat, returning the updated chat or an error.

```elixir
pub fn apply_tool_results(
  chat: Chat(@internal ToolsOn, format, @internal Ready, ext),
  calls: List(tool.Call),
  run: fn(tool.Call) -> Result(tool.ToolResult, tool.ToolError),
) -> Result(
  Chat(@internal ToolsOn, format, @internal Ready, ext),
  StarletError,
)

```

--------------------------------

### Enable JSON Output for Chat

Source: https://hexdocs.pm/starlet/starlet

Enables JSON output for the chat, constraining the model to produce responses that conform to the provided schema. Use `json(turn)` to extract the JSON string from the response.

```Rust
pub fn with_json_output(
  chat: Chat(tools, @internal FreeText, state, ext),
  output_schema: schema.Type,
) -> Chat(tools, @internal JsonFormat, state, ext)

```

--------------------------------

### PUT /temperature

Source: https://hexdocs.pm/starlet/starlet

Sets the sampling temperature (typically 0.0 to 2.0). Lower values make output more deterministic, higher values more creative.

```APIDOC
## PUT /temperature

### Description
Sets the sampling temperature (typically 0.0 to 2.0). Lower values make output more deterministic, higher values more creative.

### Method
PUT

### Endpoint
/temperature

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat** (Chat) - Required - The chat object to configure.
- **value** (Float) - Required - The temperature value (e.g., 0.7).

### Request Example
```json
{
  "chat": { ... },
  "value": 0.7
}
```

### Response
#### Success Response (200)
- **chat** (Chat) - The updated chat object with the temperature set.

#### Response Example
```json
{
  "chat": { ... }
}
```
```

--------------------------------

### POST /chat

Source: https://hexdocs.pm/starlet/starlet

Creates a new chat with the given client and model name. The chat inherits the provider’s extension type from the client, allowing provider-specific features to be configured.

```APIDOC
## POST /chat

### Description
Creates a new chat with the given client and model name. The chat inherits the provider’s extension type from the client, allowing provider-specific features to be configured.

### Method
POST

### Endpoint
/chat

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **client** (Client) - Required - The client object.
- **model** (String) - Required - The name of the model to use for the chat.

### Request Example
```json
{
  "client": { ... },
  "model": "qwen3:0.6b"
}
```

### Response
#### Success Response (200)
- **chat** (Chat) - The newly created chat object.

#### Response Example
```json
{
  "chat": { ... }
}
```
```

--------------------------------

### Chat and Conversation Management

Source: https://hexdocs.pm/starlet/starlet/openai

This section details how to initiate chat conversations, send user messages, and manage conversation history using response IDs.

```APIDOC
## POST /chat/send

### Description
Sends a user message in a chat conversation and retrieves the response.

### Method
POST

### Endpoint
/chat/send

### Parameters
#### Request Body
- **client** (starlet.Client) - Required - The OpenAI client instance.
- **model_id** (String) - Required - The ID of the model to use for chat completion (e.g., "gpt-5-nano").
- **message** (String) - Required - The user's message to send.
- **continue_from_id** (String) - Optional - The ID of a previous response to continue the conversation from.

### Request Example
```json
{
  "client": "<client_object>",
  "model_id": "gpt-5-nano",
  "message": "Hello!"
}
```

### Response
#### Success Response (200)
- **chat_response** (starlet.ChatResponse) - The response from the chat model, containing the message and potentially a response ID for continuation.

#### Response Example
```json
{
  "chat_response": {
    "message": "Hello there! How can I help you today?",
    "response_id": "resp_12345abc"
  }
}
```

## POST /chat/continue_from

### Description
Continues a conversation from a previous response ID. The server will use its stored conversation state.

### Method
POST

### Endpoint
/chat/continue_from

### Parameters
#### Request Body
- **chat** (starlet.Chat) - Required - The current chat object.
- **id** (String) - Required - The ID of the previous response to continue from.

### Request Example
```json
{
  "chat": "<chat_object>",
  "id": "resp_12345abc"
}
```

### Response
#### Success Response (200)
- **updated_chat** (starlet.Chat) - The chat object with the conversation continued.

#### Response Example
```json
{
  "updated_chat": "<updated_chat_object>"
}
```

## POST /chat/reset_response_id

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

### Method
POST

### Endpoint
/chat/reset_response_id

### Parameters
#### Request Body
- **chat** (starlet.Chat) - Required - The current chat object.

### Request Example
```json
{
  "chat": "<chat_object>"
}
```

### Response
#### Success Response (200)
- **updated_chat** (starlet.Chat) - The chat object with the response ID reset.

#### Response Example
```json
{
  "updated_chat": "<updated_chat_object>"
}
```
```

--------------------------------

### Define a Weather Tool

Source: https://hexdocs.pm/starlet/starlet/tool

Defines a function tool named 'get_weather' with a single string parameter 'city'. This tool is intended to retrieve weather information for a specified city.

```gleam
import gleam/json
import starlet/tool

let weather_tool =
  tool.function(
    name: "get_weather",
    description: "Get current weather for a city",
    parameters: json.object([
      #("type", json.string("object")),
      #("properties", json.object([
        #("city", json.object([#("type", json.string("string"))])),
      ])),
    ]),
  )

```

--------------------------------

### Add User Message to Chat

Source: https://hexdocs.pm/starlet/starlet

Appends a user message to the chat history. This action transitions the chat state to `Ready`, making it eligible to be sent to the language model.

```Rust
pub fn user(
  chat: Chat(tools_state, format, state, ext),
  text: String,
) -> Chat(tools_state, format, @internal Ready, ext)

```

--------------------------------

### Switch Chat Output from JSON to Free Text

Source: https://hexdocs.pm/starlet/starlet

Disables JSON output and reverts the chat's format to free text. This transitions the chat from `JsonFormat` to `FreeText`.

```Rust
pub fn with_free_text(
  chat: Chat(tools, @internal JsonFormat, state, ext),
) -> Chat(tools, @internal FreeText, state, ext)

```

--------------------------------

### POST /json

Source: https://hexdocs.pm/starlet/starlet

Extracts the JSON content from a turn. Only available for JSON format turns.

```APIDOC
## POST /json

### Description
Extracts the JSON content from a turn. Only available for JSON format turns.

### Method
POST

### Endpoint
/json

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **turn** (Turn) - Required - The turn object from which to extract JSON.

### Request Example
```json
{
  "turn": { ... } // Assumes turn is in JsonFormat
}
```

### Response
#### Success Response (200)
- **content** (String) - The extracted JSON content as a string.

#### Response Example
```json
{
  "content": "{\"key\": \"value\"}"
}
```
```

--------------------------------

### Extract Tool Calls from Turn

Source: https://hexdocs.pm/starlet/starlet

Extracts a list of tool calls from a chat turn. This function is only available when tools are enabled for the turn.

```Rust
pub fn tool_calls(
  turn: Turn(@internal ToolsOn, format, ext),
) -> List(tool.Call)

```

--------------------------------

### Set Sampling Temperature for Chat

Source: https://hexdocs.pm/starlet/starlet

Adjusts the sampling temperature, influencing the creativity and determinism of the model's output. Lower values yield more predictable results, while higher values encourage more creative responses.

```Rust
pub fn temperature(
  chat: Chat(tools_state, format, state, ext),
  value: Float,
) -> Chat(tools_state, format, state, ext)

```

--------------------------------

### Thinking Mode Configuration

Source: https://hexdocs.pm/starlet/starlet/ollama

Explains how to enable and configure 'thinking' capabilities for supported models in Ollama.

```APIDOC
## POST /websites/hexdocs_pm_starlet/ollama/thinking

### Description
This section details how to configure the thinking mode for capable models when using the Ollama provider with Starlet. Thinking mode allows for step-by-step reasoning.

### Method
POST (Implicitly through Starlet's chat functions)

### Endpoint
(Not a direct HTTP endpoint, but integrates with Starlet's client)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(Managed internally by Starlet's client and message formatting)

### Request Example
```starlet
import starlet
import starlet/ollama

let client = ollama.new("http://localhost:11434")

starlet.chat(client, "deepseek-r1")
|> ollama.with_thinking(ollama.ThinkingEnabled)
|> starlet.user("Solve this step by step...")
|> starlet.send()
```

### Response
#### Success Response (200)
(A Starlet Chat object configured with the specified thinking mode)

#### Response Example
(The response is a modified Starlet Chat object, not a direct string response)

```

--------------------------------

### List Available Gemini Models

Source: https://hexdocs.pm/starlet/starlet/gemini

Provides a function to list all available Gemini models using an API key. This function returns a Result containing a list of 'Model' objects or a StarletError.

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

--------------------------------

### List Gemini Models with Custom Base URL

Source: https://hexdocs.pm/starlet/starlet/gemini

Enables listing Gemini models using a specified base URL in addition to the API key. This is useful for private endpoints or specific Gemini deployments.

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

--------------------------------

### Create Starlet Anthropic Client with Custom Base URL

Source: https://hexdocs.pm/starlet/starlet/anthropic

Details the function signature for initializing an Anthropic client with a custom base URL. This is useful for scenarios involving proxies or self-hosted Anthropic API endpoints and also highlights the `max_tokens` requirement.

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

```

--------------------------------

### Model Information

Source: https://hexdocs.pm/starlet/starlet/openai

This section provides information on how to list available models from the OpenAI API.

```APIDOC
## GET /models

### Description
Lists available models from the OpenAI API.

### Method
GET

### Endpoint
/models

### Parameters
#### Query Parameters
- **api_key** (String) - Required - Your OpenAI API key.

### Request Example
```json
{
  "api_key": "YOUR_API_KEY"
}
```

### Response
#### Success Response (200)
- **models** (List[Model]) - A list of available Model objects, each containing an ID and ownership information.

#### Response Example
```json
{
  "models": [
    {
      "id": "gpt-5-nano",
      "owned_by": "openai"
    },
    {
      "id": "o1",
      "owned_by": "openai"
    }
  ]
}
```

## GET /models/with_base_url

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

### Method
GET

### Endpoint
/models/with_base_url

### Parameters
#### Query Parameters
- **api_key** (String) - Required - Your OpenAI API key.
- **base_url** (String) - Required - The custom base URL for the OpenAI API.

### Request Example
```json
{
  "api_key": "YOUR_API_KEY",
  "base_url": "YOUR_CUSTOM_BASE_URL"
}
```

### Response
#### Success Response (200)
- **models** (List[Model]) - A list of available Model objects, each containing an ID and ownership information.

#### Response Example
```json
{
  "models": [
    {
      "id": "gpt-5-nano",
      "owned_by": "openai"
    },
    {
      "id": "o1",
      "owned_by": "openai"
    }
  ]
}
```
```

--------------------------------

### Create Ollama Client and Send Chat Request

Source: https://hexdocs.pm/starlet/starlet/ollama

Initializes a new Ollama client and sends a basic chat message. This requires the starlet and starlet/ollama libraries. The function takes a client and model name, then pipes user input to the send function.

```zig
import starlet
import starlet/ollama

let client = ollama.new("http://localhost:11434")

starlet.chat(client, "qwen3:0.6b")
|> starlet.user("Hello!")
|> starlet.send()

```

--------------------------------

### Configure Gemini Thinking Mode

Source: https://hexdocs.pm/starlet/starlet/gemini

Illustrates how to enable and configure the 'thinking' mode for Gemini 2.5+ models, allowing for step-by-step problem-solving. This feature can be controlled with dynamic or fixed token budgets.

```nim
starlet.chat(client, "gemini-2.5-flash")
|> gemini.with_thinking(gemini.ThinkingDynamic)
|> starlet.user("Solve this step by step...")
|> starlet.send()
```

--------------------------------

### Check for Tool Calls in Turn

Source: https://hexdocs.pm/starlet/starlet

Determines if a given turn in a chat session contains any tool calls. This is applicable to turns where tools are enabled.

```Rust
pub fn has_tool_calls(
  turn: Turn(@internal ToolsOn, format, ext),
) -> Bool

```