Skip to main content

​
Configuration Options

Instructor provides extensive configuration options through fluent API methods to customize its behavior, processing, and integration with various LLM providers.

​
Request Configuration

Configure how Instructor processes your input and builds requests: 
$structuredOutput = (new StructuredOutput)
    ->withMessages($messages)           // Set chat messages
    ->withInput($input)                 // Set input (converted to messages)
    ->withSystem($systemPrompt)         // Set system prompt
    ->withPrompt($prompt)               // Set additional prompt
    ->withExamples($examples)           // Set example data for context
    ->withModel($modelName)             // Set LLM model name
    ->withOptions($options)             // Set LLM-specific options
    ->withOption($key, $value)          // Set individual LLM option
    ->withStreaming(true)               // Enable streaming responses
    ->withCachedContext($messages, $system, $prompt, $examples); // Use cached context
// @doctest id="ea83"

​
Response Configuration

Define how Instructor should process and validate responses: 
$structuredOutput = (new StructuredOutput)
    ->withMaxRetries(3)                 // Set retry count for failed validations
    ->withOutputMode(OutputMode::Tools) // Set output mode (Tools, Json, JsonSchema, MdJson)
    ->withDefaultToStdClass(true);      // Fallback to stdClass for schema-less payloads
// @doctest id="c679"
Stream replay policy is configured through StructuredOutputConfig: 
use Cognesy\Instructor\Config\StructuredOutputConfig;
use Cognesy\Polyglot\Inference\Enums\ResponseCachePolicy;

$structuredOutput = (new StructuredOutput)
    ->withConfig(new StructuredOutputConfig(
        responseCachePolicy: ResponseCachePolicy::None, // default in 2.0
    ));
// @doctest id="9940"
Use ResponseCachePolicy::Memory if you need second-pass replay of streamed updates.

​
Advanced Configuration

Fine-tune Instructor’s internal processing: 
$structuredOutput = (new StructuredOutput)
    ->withConfig($configObject)         // Use custom StructuredOutputConfig instance
    ->withDefaultToStdClass(true);      // Default to stdClass for unknown types
// @doctest id="4720"

​
LLM Provider Configuration

Configure connection and communication with LLM providers: 
use Cognesy\Instructor\StructuredOutputRuntime;
use Cognesy\Polyglot\Inference\LLMProvider;

$structuredOutput = StructuredOutput::using('openai');

$structuredOutput = (new StructuredOutput)->withRuntime(
    StructuredOutputRuntime::fromDsn('preset=openai,model=gpt-4o-mini')
);

$provider = LLMProvider::using('openai')
    ->withConfigOverrides(['temperature' => 0.2]);
$structuredOutput = (new StructuredOutput)->withRuntime(
    StructuredOutputRuntime::fromProvider(provider: $provider)
);
// @doctest id="e831"
StructuredOutputRuntime also supports:
  • fromConfig(LLMConfig $config) - start from explicit LLMConfig
  • fromResolver(CanResolveLLMConfig $resolver) - plug your own resolver
  • fromDefaults() - use defaults with optional event/http overrides
Runtime accessors are useful for diagnostics and DI wiring:
  • config()
  • events()
  • validators(), transformers(), deserializers(), extractors()

​
Processing Pipeline Overrides

Customize validation, transformation, and deserialization: 
$structuredOutput = (new StructuredOutput)
    ->withValidators(...$validators)    // Override response validators
    ->withTransformers(...$transformers) // Override response transformers  
    ->withDeserializers(...$deserializers) // Override response deserializers
    ->withExtractors(...$extractors);    // Override response extractors
// @doctest id="f260"

​
StructuredOutputConfig Knobs

Besides outputMode, maxRetries, and responseCachePolicy, you can tune:
  • schemaName / schemaDescription - schema metadata sent to the model
  • toolName / toolDescription - tool-call metadata in OutputMode::Tools
  • retryPrompt - feedback prompt used for recovery attempts
  • modePrompts - per-mode prompt templates
  • useObjectReferences - schema rendering behavior for object references
  • defaultToStdClass - fallback type for schema-less payloads
  • throwOnTransformationFailure - fail-fast behavior for transform step
  • chatStructure - order of template sections used to build final prompt
Example: 
use Cognesy\Instructor\Config\StructuredOutputConfig;
use Cognesy\Instructor\StructuredOutput;
use Cognesy\Polyglot\Inference\Enums\OutputMode;
use Cognesy\Polyglot\Inference\Enums\ResponseCachePolicy;

$config = new StructuredOutputConfig(
    outputMode: OutputMode::Tools,
    toolName: 'extract_person',
    toolDescription: 'Extract person attributes from user content',
    maxRetries: 2,
    responseCachePolicy: ResponseCachePolicy::Memory,
);

$result = (new StructuredOutput)
    ->withConfig($config)
    ->withMessages('Extract person data')
    ->withResponseClass(Person::class)
    ->get();
// @doctest id="dcf1"

​
Streaming Updates And Events

Handle incremental updates via stream iterators or event subscribers: 
$stream = (new StructuredOutput)
    ->withStreaming(true)
    ->withMessages("Generate a list of tasks")
    ->withResponseModel(Sequence::of(Task::class))
    ->stream();

foreach ($stream->partials() as $partial) {
    updateUI($partial);
}

foreach ($stream->sequence() as $sequence) {
    processItem($sequence->last());
}

$structuredOutput = (new StructuredOutput)
    ->onEvent(\Cognesy\Instructor\Events\PartialsGenerator\PartialResponseGenerated::class, $callback)
    ->onEvent(\Cognesy\Instructor\Events\Request\SequenceUpdated::class, $callback);
// @doctest id="0d09"

​
Configuration Examples

​
Basic OpenAI Configuration

$result = StructuredOutput::using('openai')
    ->withModel('gpt-4')
    ->withMaxRetries(3)
    ->withMessages("Extract person data from: John is 25 years old")
    ->withResponseClass(Person::class)
    ->get();
// @doctest id="1566"

​
Streaming with partials()

$stream = StructuredOutput::using('openai')
    ->withStreaming(true)
    ->withMessages("Generate a list of tasks")
    ->withResponseModel(Sequence::of(Task::class))
    ->stream();

foreach ($stream->partials() as $partial) {
    updateUI($partial);
}

$result = $stream->finalValue();
// @doctest id="256b"

​
Custom Configuration Object

$config = new StructuredOutputConfig(
    maxRetries: 5,
    outputMode: OutputMode::JsonSchema,
    retryPrompt: "Please fix the validation errors and try again."
);

$result = (new StructuredOutput)
    ->withConfig($config)
    ->withMessages($input)
    ->withResponseClass(Person::class)
    ->get();
// @doctest id="ff07"