Skip to main content
The ChatPreconfiguredModelBuilder provides a fluent interface for building and executing chat conversations with language models. It supports messages, tools, streaming, and various callbacks.

​
Configuration Methods

​
model

Set the LLM model to use for the chat. 
$builder->model('gpt-4o')
​
model
string|LLM
required
The model identifier string (e.g., ‘gpt-4o’, ‘claude-3-5-sonnet’) or LLM instance
​
return
static
Returns the builder instance for method chaining

​
system

Set the system prompt for the conversation. 
$builder->system('You are a helpful assistant')
​
prompt
string|null
required
The system prompt to guide the model’s behavior
​
return
static
Returns the builder instance for method chaining

​
prompt

Set a simple user prompt (alternative to using messages). 
$builder->prompt('What is the capital of France?')
​
prompt
Prompt|string|null
required
The user prompt text or Prompt instance
​
return
static
Returns the builder instance for method chaining

​
messages

Set the conversation messages. 
$builder->messages([
    TextMessage::user('Hello'),
    TextMessage::assistant('Hi there!')
])
​
messages
Message[]
required
Array of Message instances (TextMessage, ToolCallMessage, ToolResultMessage)
​
return
static
Returns the builder instance for method chaining

​
addMessage

Add a single message to the conversation. 
$builder->addMessage(TextMessage::user('Follow-up question'))
​
message
Message
required
The message to add
​
return
static
Returns the builder instance for method chaining

​
addMessages

Add multiple messages to the conversation. 
$builder->addMessages([
    TextMessage::user('Question 1'),
    TextMessage::user('Question 2')
])
​
messages
Message[]
required
Array of messages to add
​
return
static
Returns the builder instance for method chaining

​
Tool Methods

​
tools

Register tools that the model can call. 
$builder->tools([
    'search' => fn(string $query) => searchDatabase($query),
    'calculate' => new CalculatorTool()
])
​
tools
mixed
required
Array of tools (closures or InvokableTool instances) with string keys as tool names
​
return
static
Returns the builder instance for method chaining

​
toolChoice

Set the tool choice strategy. 
$builder->toolChoice('search') // Force specific tool
$builder->toolChoice(ToolChoice::Auto) // Let model choose
​
name
ToolChoice|string
default:"ToolChoice::Auto"
Tool choice mode: ToolChoice::Auto, ToolChoice::Required, or a specific tool name
​
return
static
Returns the builder instance for method chaining

​
forceTool

Force the model to use a tool. 
$builder->forceTool('search')
​
name
ToolChoice|string
default:"ToolChoice::Required"
The tool name to force, or ToolChoice::Required to require any tool
​
return
static
Returns the builder instance for method chaining

​
interrupt

Set a callback to interrupt execution before tool calls. 
$builder->interrupt(function(ToolCall $call) {
    return $call->name === 'dangerous_operation';
})
​
shouldInterrupt
Closure|null
required
Closure that receives a ToolCall and returns bool. True interrupts execution.
​
return
static
Returns the builder instance for method chaining

​
onToolError

Set a callback for tool execution errors. 
$builder->onToolError(function(Throwable $e) {
    Log::error('Tool error: ' . $e->getMessage());
})
​
onToolError
Closure|null
required
Closure that receives the Throwable exception
​
return
static
Returns the builder instance for method chaining

​
Callback Methods

​
onMessage

Set a callback for completed messages. 
$builder->onMessage(function(Message $message) {
    echo "Received: " . $message->content;
})
​
onMessage
Closure(Message): void|null
required
Closure that receives each completed Message
​
return
static
Returns the builder instance for method chaining

​
onMessageProgress

Set a callback for streaming message progress. 
$builder->onMessageProgress(function(Message $message) {
    echo $message->content;
})
​
onMessageProgress
Closure(Message): void|null
required
Closure that receives partial Messages during streaming
​
return
static
Returns the builder instance for method chaining

​
onTokenStats

Set a callback for token usage statistics. 
$builder->onTokenStats(function(TokenStats $stats) {
    echo "Tokens used: {$stats->total}";
})
​
onTokenStats
Closure(TokenStats): void|null
required
Closure that receives TokenStats with usage information
​
return
static
Returns the builder instance for method chaining

​
Configuration Methods

​
attempts

Set the maximum number of retry attempts for tool errors. 
$builder->attempts(5)
​
attempts
int
required
Maximum number of attempts (default: 3)
​
return
static
Returns the builder instance for method chaining

​
debugger

Attach a debugger for logging conversation details. 
$builder->debugger(new FileDebugger('chat.log'))
​
debugger
FileDebugger|null
required
FileDebugger instance or null to disable debugging
​
return
static
Returns the builder instance for method chaining

​
schema

Set a JSON schema for structured output validation. 
$builder->schema([
    'type' => 'object',
    'properties' => [
        'name' => ['type' => 'string'],
        'age' => ['type' => 'number']
    ]
])
​
schema
array
required
JSON schema array defining the expected output structure
​
return
static
Returns the builder instance for method chaining

​
Execution Methods

​
stream

Execute the chat with streaming responses. 
$messages = $builder->stream()
​
return
MessageCollection
Collection of messages from the conversation, including responses and tool calls

​
send

Execute the chat without streaming (waits for complete response). 
$messages = $builder->send()
​
return
MessageCollection
Collection of messages from the conversation

​
build

Build a Prompt object from the current configuration. 
$prompt = $builder->build()
​
return
Prompt
A Prompt object containing the system message, messages, tools, and configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us