Events

Overview

Instructor dispatches events at every significant stage of its execution. You can listen to these events for logging, monitoring, debugging, or custom processing. All event classes extend Cognesy\Events\Event.

Listening to Events

Targeted Listeners

Use onEvent() on the StructuredOutputRuntime to listen for a specific event type:

use Cognesy\Instructor\Events\Response\ResponseValidationFailed;

$runtime = StructuredOutputRuntime::fromDefaults()
    ->onEvent(ResponseValidationFailed::class, function ($event) {
        logger()->warning('Validation failed', $event->toArray());
    });
// @doctest id="5772"

Wiretap (All Events)

Use wiretap() to receive every event dispatched by Instructor. This is useful for debugging or comprehensive logging:

$runtime = StructuredOutputRuntime::fromDefaults()
    ->wiretap(fn($event) => $event->print());
// @doctest id="f2fb"

Practical Example

use Cognesy\Instructor\StructuredOutput;
use Cognesy\Instructor\StructuredOutputRuntime;
use Cognesy\Instructor\Extras\Scalar\Scalar;
use Cognesy\Http\Events\HttpRequestSent;
use Cognesy\Http\Events\HttpResponseReceived;

$runtime = StructuredOutputRuntime::fromDefaults()
    // Log HTTP-level details
    ->onEvent(HttpRequestSent::class, fn($e) => dump($e))
    ->onEvent(HttpResponseReceived::class, fn($e) => dump($e))
    // Console-friendly output for all events
    ->wiretap(fn($event) => $event->print())
    // Structured logging
    ->wiretap(fn($event) => YourLogger::log($event->asLog()));

$result = (new StructuredOutput($runtime))
    ->with(
        messages: 'What is the population of Paris?',
        responseModel: Scalar::integer(),
    )
    ->get();
// @doctest id="bfc2"

Event Categories

Events are organized into namespaces that correspond to the processing stage:

High-Level Events (`Events\StructuredOutput`)

Event	When
`StructuredOutputStarted`	A structured output operation begins
`StructuredOutputRequestReceived`	The request has been received by the runtime
`StructuredOutputResponseGenerated`	The final `StructuredOutputResponse` has been produced
`StructuredOutputResponseUpdated`	A streaming partial response is emitted

Request Events (`Events\Request`)

Event	When
`ResponseModelRequested`	A response model has been submitted for processing
`ResponseModelBuildModeSelected`	The factory has chosen a build strategy
`ResponseModelBuilt`	The response model and schema are ready
`NewValidationRecoveryAttempt`	A retry attempt is about to begin
`StructuredOutputRecoveryLimitReached`	All retries have been exhausted
`SequenceUpdated`	A sequence item has been completed during streaming

Response Events (`Events\Response`)

Event	When
`ResponseDeserializationAttempt`	Deserialization is about to start
`ResponseDeserialized`	Deserialization succeeded
`ResponseDeserializationFailed`	Deserialization failed
`CustomResponseDeserializationAttempt`	A `CanDeserializeSelf` implementation is being used
`ResponseValidationAttempt`	Validation is about to start
`ResponseValidated`	Validation passed
`ResponseValidationFailed`	Validation failed
`CustomResponseValidationAttempt`	A `CanValidateSelf` implementation is being used
`ResponseTransformationAttempt`	Transformation is about to start
`ResponseTransformed`	Transformation succeeded
`ResponseTransformationFailed`	Transformation failed
`ResponseConvertedToObject`	The final object has been produced
`ResponseGenerationFailed`	The entire response generation pipeline failed

Extraction Events (`Events\Extraction`)

Event	When
`ExtractionStarted`	Data extraction from the inference response begins
`ExtractionCompleted`	Extraction succeeded
`ExtractionFailed`	Extraction failed
`ExtractionStrategyAttempted`	A specific extraction strategy is being tried
`ExtractionStrategySucceeded`	The strategy produced a result
`ExtractionStrategyFailed`	The strategy did not produce a result

Streaming Events (`Events\PartialsGenerator`)

Event	When
`ChunkReceived`	A raw chunk arrived from the provider
`StreamedResponseReceived`	A streamed response chunk was processed
`StreamedResponseFinished`	The stream has ended
`PartialJsonReceived`	A partial JSON fragment was accumulated
`PartialResponseGenerated`	A partial deserialized response is available
`PartialResponseGenerationFailed`	Partial deserialization failed (non-fatal)
`StreamedToolCallStarted`	A tool call began in the stream
`StreamedToolCallUpdated`	A tool call received more data
`StreamedToolCallCompleted`	A tool call finished

Event Methods

Every event inherits the following convenience methods from Cognesy\Events\Event:

Method	Description
`print()`	Print a console-friendly representation
`printLog()`	Print a log-formatted representation
`printDebug()`	Print console output and dump the full event object
`asConsole()`	Return the event formatted for console output
`asLog()`	Return the event formatted for log output
`toArray()`	Return the event data as an associative array
`name()`	Return the short class name of the event

Events carry a $logLevel property (PSR log level) and a $data payload. The print() method respects a configurable log-level threshold. Instructor event payloads are normalized arrays. Structured-output lifecycle events also expose correlation fields such as requestId, executionId, attemptId, phase, and phaseId where applicable.

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

Overview

Listening to Events

Targeted Listeners

Wiretap (All Events)

Practical Example

Event Categories

High-Level Events (`Events\StructuredOutput`)

Request Events (`Events\Request`)

Response Events (`Events\Response`)

Extraction Events (`Events\Extraction`)

Streaming Events (`Events\PartialsGenerator`)

Event Methods

​Overview

​Listening to Events

​Targeted Listeners

​Wiretap (All Events)

​Practical Example

​Event Categories

​High-Level Events (Events\StructuredOutput)

​Request Events (Events\Request)

​Response Events (Events\Response)

​Extraction Events (Events\Extraction)

​Streaming Events (Events\PartialsGenerator)

​Event Methods

Overview

Listening to Events

Targeted Listeners

Wiretap (All Events)

Practical Example

Event Categories

High-Level Events (`Events\StructuredOutput`)

Request Events (`Events\Request`)

Response Events (`Events\Response`)

Extraction Events (`Events\Extraction`)

Streaming Events (`Events\PartialsGenerator`)

Event Methods