Functions

`assistant-message`

fn (content: Str): InputMessage

Create an assistant message for providing conversation history.

Example

msg assistant-message("Nice to meet you!")
msg.role // => "assistant"

// Use in multi-turn input
response create(CreateResponseRequest({
    model: "grok-3-mini",
    input: [
        user-message("My name is Alice."),
        assistant-message("Nice to meet you, Alice!"),
        user-message("What is my name?")
    ]
}))

`chat`

fn (model: Str, message: Str): Str
fn (model: Str, message: Str, system: Str): Str
fn (model: Str, message: Str, system: Str, max-tokens: Int): Str

Simple chat - send a message and get a response string.

Accepts an optional system instruction and max token limit. This is a convenience wrapper around create() that returns the extracted text directly.

Example

answer chat("grok-3", "What is the capital of France?")
// => "The capital of France is Paris."

// With system instructions
answer chat("grok-3-mini", "What is 2+2?", "Respond with just the number.")
// => "4"

`create`

fn (request: CreateResponseRequest): CreateResponseResponse

Create a response (non-streaming).

The Responses API is the recommended way to interact with xAI models. It supports stateful conversations where previous prompts and responses are stored server-side for 30 days.

Example

response create(CreateResponseRequest({
    model: "grok-3-mini",
    input: "What is the capital of France?",
    max_output_tokens: 1024
}))

response.id // => "resp_abc123..."
response.output // => [{type: "message", ...}]

With conversation history

response create(CreateResponseRequest({
    model: "grok-3-mini",
    input: [
        {role: "user", content: "My name is Alice."},
        {role: "assistant", content: "Nice to meet you, Alice!"},
        {role: "user", content: "What is my name?"}
    ],
    max_output_tokens: 100
}))

Continue a previous conversation

response create(CreateResponseRequest({
    model: "grok-3",
    input: "Tell me more",
    previous_response_id: "resp_abc123"
}))

`create-stream`

fn (request: CreateResponseRequest): StreamingResponseResponse

Create a streaming response. Returns a StreamingResponseResponse with an iterator body that yields SSE events.

Event Types

response.created - Initial response metadata
response.output_item.added - New output item started
response.content_part.added - Content part started
response.output_text.delta - Text chunk
response.output_text.done - Text output complete
response.output_item.done - Output item complete
response.completed - Full response complete

Example

response create-stream(CreateResponseRequest({
    model: "grok-3-mini",
    input: "Count from 1 to 3.",
    max_output_tokens: 50
}))

response.status // => 200

events collect(response.body)
// events is a Vec of SSE event objects

`delete`

fn (response-id: Str): Map

Delete a stored response. This removes it from server-side storage.

Example

delete("resp_abc123")

`extract-delta-text`

fn (event): Str

Extract the text content from a streaming SSE event. Returns empty string if the event is not a text delta.

Only extracts text from events with type "response.output_text.delta".

Example

response create-stream(CreateResponseRequest({
    model: "grok-3-mini",
    input: "Say hello"
}))

for-each(response.body, (event) {
    text extract-delta-text(event)
    // text contains the delta chunk, or "" for non-text events
})

`extract-response-text`

fn (response: CreateResponseResponse): Str

Extract the text content from a response. Returns empty string if no text content is found.

Walks through the response output items, finds the first "message" item, and extracts the first "output_text" content part.

Example

response create(CreateResponseRequest({
    model: "grok-3-mini",
    input: "Say 'test'",
    max_output_tokens: 50
}))

text extract-response-text(response)
is-str(text) // => true

`get`

fn (response-id: Str): CreateResponseResponse

Retrieve a previously created response by ID.

Requires that the response was created with store: true (which is the default).

Example

// Create with store: true (default)
created create(CreateResponseRequest({
    model: "grok-3-mini",
    input: "Say hello",
    store: true
}))

// Later, retrieve it
retrieved get(created.id)
eq(created.id, retrieved.id) // => true

`is-stream-done`

fn (event): Bool

Check if a streaming event indicates the stream is complete.

Returns true for event types: "response.completed", "response.failed", or "response.incomplete".

Example

for-each(response.body, (event) {
    cond {
        is-stream-done(event) => { "Stream finished" }
        => {
            text extract-delta-text(event)
            // process text chunk
        }
    }
})

`system-message`

fn (content: Str): InputMessage

Create a system message for setting model behavior.

Example

msg system-message("You are a helpful math tutor.")
msg.role // => "system"
msg.content // => "You are a helpful math tutor."

`user-message`

fn (content: Str): InputMessage

Create a user message for use in multi-turn conversations.

Example

msg user-message("Hello")
msg.role // => "user"
msg.content // => "Hello"

Types

`ContentPart`

ContentPart type {
    type: Str,
    text: Str?,
    annotations: Vec?
}

`CreateResponseRequest`

CreateResponseRequest type {
    model: Str,
    input: Any,
    instructions: Str?,
    max_output_tokens: Int?,
    temperature: Dec?,
    top_p: Dec?,
    tools: Vec?,
    tool_choice: Any?,
    parallel_tool_calls: Bool?,
    response_format: ResponseFormat?,
    store: Bool?,
    metadata: Map?,
    stream: Bool?,
    reasoning: ReasoningConfig?,
    previous_response_id: Str?
}

`CreateResponseResponse`

CreateResponseResponse type {
    id: Str,
    object: Str,
    created_at: Int,
    model: Str,
    status: ResponseStatus,
    output: Vec,
    usage: Usage?,
    error: Any?,
    incomplete_details: Any?,
    metadata: Map?
}

`FinishReason`

FinishReason type "stop" | "length" | "tool_calls" | "content_filter"

`FunctionCall`

FunctionCall type {
    name: Str,
    arguments: Str
}

`FunctionDefinition`

FunctionDefinition type {
    name: Str,
    description: Str?,
    parameters: Any?,
    strict: Bool?
}

`InputMessage`

InputMessage type {
    role: Role,
    content: Any,
    name: Str?,
    tool_calls: Vec?,
    tool_call_id: Str?
}

`OutputItem`

OutputItem type {
    type: Str,
    id: Str?,
    status: Str?,
    role: Role?,
    content: Vec?,
    name: Str?,
    arguments: Str?,
    call_id: Str?,
    output: Str?
}

`ReasoningConfig`

ReasoningConfig type {
    effort: Str?,
    encrypted_content: Str?
}

`ResponseFormat`

ResponseFormat type {
    type: Str,
    json_schema: Any?
}

`ResponseStatus`

ResponseStatus type "completed" | "failed" | "incomplete" | "in_progress"

`Role`

Role type "user" | "system" | "assistant" | "tool"

`StreamEvent`

StreamEvent type {
    type: Str,
    response: CreateResponseResponse?,
    output_index: Int?,
    item: OutputItem?,
    content_index: Int?,
    part: ContentPart?,
    delta: Str?
}

`StreamingResponseResponse`

StreamingResponseResponse type {
    status: Int,
    headers: Map,
    body: Any
}

`TokenDetails`

TokenDetails type {
    cached_tokens: Int?,
    reasoning_tokens: Int?
}

`Tool`

Tool type {
    type: Str,
    function: FunctionDefinition
}

`ToolCall`

ToolCall type {
    id: Str,
    type: Str,
    function: FunctionCall
}

`Usage`

Usage type {
    input_tokens: Int,
    output_tokens: Int,
    total_tokens: Int?,
    input_tokens_details: TokenDetails?,
    output_tokens_details: TokenDetails?
}

::models ::search