Skip to main content
Instructor provides several levels of configuration for controlling which model is used and how requests are sent to the LLM provider.

​
Per-Request Options

The simplest way to control the model and options is to pass them directly in the request. This is ideal for one-off adjustments. 
use Cognesy\Instructor\StructuredOutput;

$person = (new StructuredOutput)->with(
    messages: $text,
    responseModel: Person::class,
    model: 'gpt-4o-mini',
    options: ['temperature' => 0],
)->get();
// @doctest id="647e"
You can also use the fluent API for the same result. 
$person = (new StructuredOutput)
    ->withMessages($text)
    ->withResponseClass(Person::class)
    ->withModel('gpt-4o-mini')
    ->withOptions(['temperature' => 0])
    ->get();
// @doctest id="6eb6"
The options array is passed directly to the LLM provider. Common options include temperature, max_tokens, and top_p, though available options vary by provider and model.

​
Using LLMConfig

When you need consistent settings across multiple requests — such as a custom API key, base URL, or organization — use LLMConfig to construct a configured StructuredOutput instance. 
use Cognesy\Instructor\StructuredOutput;
use Cognesy\Polyglot\Inference\Config\LLMConfig;

$config = new LLMConfig(
    apiUrl: 'https://api.openai.com/v1',
    apiKey: $yourApiKey,
    endpoint: '/chat/completions',
    metadata: ['organization' => ''],
    model: 'gpt-4o-mini',
    maxTokens: 128,
    driver: 'openai',
);

$structuredOutput = StructuredOutput::fromConfig($config);

$person = $structuredOutput->with(
    messages: $text,
    responseModel: Person::class,
    options: ['temperature' => 0],
)->get();
// @doctest id="a725"
Per-request model and options values override the corresponding LLMConfig defaults, so you can set sensible defaults in the config and adjust individual requests as needed.

​
Using Presets

If you have named LLM configurations defined in a configuration file, you can load them by name. 
$person = StructuredOutput::using('anthropic')
    ->with(messages: $text, responseModel: Person::class)
    ->get();
// @doctest id="bf37"
The preset name is resolved through LLMConfig::fromPreset(), which loads the connection details from your configuration.

​
Using StructuredOutputRuntime

For the highest level of control, create a StructuredOutputRuntime directly. This gives you access to output mode, retry settings, custom validators, transformers, deserializers, and extractors. 
use Cognesy\Instructor\StructuredOutput;
use Cognesy\Instructor\StructuredOutputRuntime;
use Cognesy\Instructor\Enums\OutputMode;

$runtime = StructuredOutputRuntime::fromDefaults()
    ->withOutputMode(OutputMode::Json)
    ->withMaxRetries(3);

$person = (new StructuredOutput($runtime))
    ->with(messages: $text, responseModel: Person::class)
    ->get();
// @doctest id="e1ee"

​
Common Options

These options are widely supported across providers, though exact behavior may vary.
OptionTypeDescription
temperaturefloatControls randomness. Lower values (e.g. 0) produce more deterministic output.
max_tokensintMaximum number of tokens in the response.
top_pfloatNucleus sampling threshold.
stoparrayStop sequences that end generation.
streamboolEnable streaming (prefer withStreaming() instead).
Provider-specific options (such as response_format for OpenAI or thinking for Anthropic) can also be passed through the options array. Consult your provider’s API documentation for details.