Configuration

Instructor separates configuration into three layers: the LLM provider, the runtime, and the individual request. This keeps most applications simple — one runtime handles shared behavior, while each request stays focused on content.

Provider Configuration

Use LLMConfig to choose which provider and model to connect to. The simplest approach is a preset name that maps to your environment variables:

use Cognesy\Polyglot\Inference\Config\LLMConfig;

$config = LLMConfig::fromPreset('openai');
// @doctest id="e10c"

You can also create a StructuredOutput directly from a preset:

use Cognesy\Instructor\StructuredOutput;

$result = StructuredOutput::using('anthropic')
    ->with(messages: 'Jason is 28.', responseModel: Person::class)
    ->get();
// @doctest id="160b"

Provider configuration covers connection details: API keys, base URLs, default model names, and HTTP client settings.

Runtime Configuration

StructuredOutputRuntime holds behavior that is shared across many requests. Create one runtime and reuse it throughout your application:

use Cognesy\Instructor\StructuredOutputRuntime;
use Cognesy\Instructor\Enums\OutputMode;
use Cognesy\Polyglot\Inference\Config\LLMConfig;

$runtime = StructuredOutputRuntime::fromConfig(
    LLMConfig::fromPreset('openai')
)
    ->withMaxRetries(3)
    ->withOutputMode(OutputMode::Tools);
// @doctest id="bb5f"

Runtime Settings

Method	Purpose
`withMaxRetries($n)`	Number of retry attempts after validation failure
`withOutputMode($mode)`	How the model produces structured output (Tools, Json, etc.)
`withValidator($validator)`	Override the validator (implements `CanValidateObject`)
`withTransformer($transformer)`	Override the response transformer (implements `CanTransformData`)
`withDeserializer($deserializer)`	Override the deserializer (implements `CanDeserializeClass`)
`withExtractor($extractor)`	Override the response extractor (implements `CanExtractResponse`)
`withConfig($config)`	Pass a full `StructuredOutputConfig` object
`withDefaultToStdClass($bool)`	Fall back to `stdClass` for unknown types

Advanced Configuration With `StructuredOutputConfig`

For fine-grained control, build a StructuredOutputConfig directly:

use Cognesy\Instructor\Config\StructuredOutputConfig;
use Cognesy\Instructor\Enums\OutputMode;

$config = new StructuredOutputConfig(
    outputMode: OutputMode::JsonSchema,
    maxRetries: 5,
    retryPrompt: 'Fix the validation errors and try again.',
    toolName: 'extract_data',
    toolDescription: 'Extract structured data from the input.',
);

$runtime = StructuredOutputRuntime::fromConfig(
    LLMConfig::fromPreset('openai'),
    structuredConfig: $config,
);
// @doctest id="7de6"

StructuredOutputConfig includes settings for:

Output mode — which structured output strategy to use
Retry behavior — max retries and the prompt sent on validation failure
Tool metadata — tool name and description for OutputMode::Tools
Schema metadata — schema name and description
Mode prompts — per-mode prompt templates (e.g., how JSON Schema is embedded)
Chat structure — the ordering of prompt sections
Deserialization — error prompt template, stdClass fallback, object references

Request Configuration

StructuredOutput handles per-request concerns. These are the things that change from one call to the next:

use Cognesy\Instructor\StructuredOutput;

$person = (new StructuredOutput)
    ->withRuntime($runtime)
    ->with(
        messages: 'Jason is 28 years old.',
        responseModel: Person::class,
        system: 'Extract accurate data.',
        prompt: 'Identify the person in the text.',
        model: 'gpt-4o',
    )
    ->get();
// @doctest id="5cdc"

Request Methods

Method	Purpose
`withMessages(...)`	Set the chat messages
`withInput(...)`	Input data (string, array, or object)
`withResponseModel(...)`	Response model (class, instance, or schema)
`withSystem(...)`	System prompt text (`string\|\Stringable`)
`withPrompt(...)`	Additional prompt text (`string\|\Stringable`)
`withExamples(...)`	Few-shot examples
`withModel(...)`	Model name override
`withOptions(...)`	Provider-specific options
`withStreaming(...)`	Enable streaming
`withCachedContext(...)`	Cached context for prompt caching

Event Handling

The runtime exposes an event system for observing the processing pipeline:

use Cognesy\Instructor\Events\StructuredOutput\StructuredOutputRequestReceived;

$runtime->onEvent(StructuredOutputRequestReceived::class, function ($event) {
    logger()->info('Request received', [
        'requestId' => $event->data['requestId'],
        'executionId' => $event->data['executionId'],
        'phaseId' => $event->data['phaseId'],
    ]);
});

// Or listen to all events
$runtime->wiretap(function ($event) {
    logger()->debug(get_class($event));
});
// @doctest id="6918"

Putting It Together

A typical application creates one runtime at bootstrap and passes it to each request:

// Bootstrap
$runtime = StructuredOutputRuntime::fromConfig(
    LLMConfig::fromPreset('openai')
)->withMaxRetries(2);

// Request 1
$person = (new StructuredOutput)
    ->withRuntime($runtime)
    ->with(messages: $text1, responseModel: Person::class)
    ->get();

// Request 2
$summary = (new StructuredOutput)
    ->withRuntime($runtime)
    ->with(messages: $text2, responseModel: Summary::class)
    ->get();
// @doctest id="831d"

This keeps configuration centralized and each request minimal.

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

Provider Configuration

Runtime Configuration

Runtime Settings

Advanced Configuration With `StructuredOutputConfig`

Request Configuration

Request Methods

Event Handling

Putting It Together

​Provider Configuration

​Runtime Configuration

​Runtime Settings

​Advanced Configuration With StructuredOutputConfig

​Request Configuration

​Request Methods

​Event Handling

​Putting It Together

Provider Configuration

Runtime Configuration

Runtime Settings

Advanced Configuration With `StructuredOutputConfig`

Request Configuration

Request Methods

Event Handling

Putting It Together