Events¶

Instructor dispatches events throughout the extraction and inference lifecycle. These events are automatically bridged to Laravel's event system by the LaravelEventDispatcher, allowing you to listen and respond using standard Laravel patterns -- listeners, subscribers, closures, and queued handlers.

The bridge is implemented by Cognesy\Instructor\Laravel\Events\LaravelEventDispatcher, which lives in the packages/laravel package. It wraps Laravel's native Illuminate\Contracts\Events\Dispatcher and forwards Instructor events to it based on your configuration.

Event Bridge Configuration¶

Configure event bridging in config/instructor.php:

'events' => [
    // Enable bridging to Laravel's event dispatcher
    'dispatch_to_laravel' => env('INSTRUCTOR_DISPATCH_EVENTS', true),

    // Specify which events to bridge (empty = all events)
    'bridge_events' => [
        // Only bridge specific events
        \Cognesy\Instructor\Events\Extraction\ExtractionCompleted::class,
        \Cognesy\Instructor\Events\Extraction\ExtractionFailed::class,
    ],
],

When bridge_events is empty (the default), every Instructor event is forwarded to Laravel's dispatcher. To reduce overhead in production, list only the event classes your listeners actually need.

The bridge uses instanceof matching, so listing a parent event class also bridges its subclasses.

Available Events¶

All events extend Cognesy\Instructor\Events\StructuredOutputEvent (which extends Cognesy\Events\Event). Events carry data in the $data property (an array or mixed value) rather than typed properties.

Extraction Events¶

Namespace: Cognesy\Instructor\Events\Extraction

Event	Description
`ExtractionStarted`	Extraction pipeline has begun processing
`ExtractionCompleted`	Extraction completed successfully
`ExtractionFailed`	All extraction strategies failed
`ExtractionStrategyAttempted`	An extraction strategy was attempted
`ExtractionStrategyFailed`	An extraction strategy failed
`ExtractionStrategySucceeded`	An extraction strategy succeeded

Response Events¶

Namespace: Cognesy\Instructor\Events\Response

Event	Description
`ResponseValidationFailed`	Response failed validation
`ResponseValidated`	Response passed validation
`ResponseDeserialized`	Response was deserialized into an object
`ResponseDeserializationFailed`	Response deserialization failed
`ResponseTransformed`	Response was transformed
`ResponseTransformationFailed`	Response transformation failed
`ResponseGenerationFailed`	Response generation failed

Request Events¶

Namespace: Cognesy\Instructor\Events\Request

Event	Description
`NewValidationRecoveryAttempt`	A validation recovery retry attempt is being made
`StructuredOutputRecoveryLimitReached`	Maximum retries exhausted
`ResponseModelRequested`	Response model was requested
`ResponseModelBuilt`	Response model schema was built

Streaming Events¶

Namespace: Cognesy\Instructor\Events\PartialsGenerator

Event	Description
`StreamedResponseReceived`	Streaming response started
`ChunkReceived`	Received a chunk of streaming data
`StreamedResponseFinished`	Streaming completed
`PartialResponseGenerated`	A partial response object was generated
`StreamedToolCallStarted`	A streamed tool call started
`StreamedToolCallUpdated`	A streamed tool call was updated
`StreamedToolCallCompleted`	A streamed tool call completed

Listening to Events¶

Using Event Listeners¶

Create a dedicated listener class and register it with Laravel's event system.

// app/Listeners/LogExtractionCompleted.php
namespace App\Listeners;

use Cognesy\Instructor\Events\Extraction\ExtractionCompleted;
use Illuminate\Support\Facades\Log;

class LogExtractionCompleted
{
    public function handle(ExtractionCompleted $event): void
    {
        Log::info('Extraction completed', [
            'event' => $event->name(),
            'data' => $event->data,
        ]);
    }
}

Register in EventServiceProvider:

// app/Providers/EventServiceProvider.php
namespace App\Providers;

use App\Listeners\LogExtractionCompleted;
use Cognesy\Instructor\Events\Extraction\ExtractionCompleted;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        ExtractionCompleted::class => [
            LogExtractionCompleted::class,
        ],
    ];
}

Using Closures¶

For lightweight listeners, register closures directly in a service provider's boot method.

// app/Providers/AppServiceProvider.php
use Cognesy\Instructor\Events\Extraction\ExtractionCompleted;
use Cognesy\Instructor\Events\Extraction\ExtractionFailed;
use Illuminate\Support\Facades\Event;

public function boot(): void
{
    Event::listen(ExtractionCompleted::class, function ($event) {
        // Handle successful extraction
    });

    Event::listen(ExtractionFailed::class, function ($event) {
        // Handle failed extraction
    });
}

Using Event Subscribers¶

Group related event handlers into a single subscriber class. This is convenient when you need to handle multiple Instructor events together.

// app/Listeners/InstructorEventSubscriber.php
namespace App\Listeners;

use Cognesy\Instructor\Events\Extraction\ExtractionCompleted;
use Cognesy\Instructor\Events\Extraction\ExtractionFailed;
use Cognesy\Instructor\Events\Extraction\ExtractionStarted;
use Illuminate\Events\Dispatcher;

class InstructorEventSubscriber
{
    public function handleStart(ExtractionStarted $event): void
    {
        // Log start
    }

    public function handleComplete(ExtractionCompleted $event): void
    {
        // Log completion
    }

    public function handleFailed(ExtractionFailed $event): void
    {
        // Alert on failure
    }

    public function subscribe(Dispatcher $events): array
    {
        return [
            ExtractionStarted::class => 'handleStart',
            ExtractionCompleted::class => 'handleComplete',
            ExtractionFailed::class => 'handleFailed',
        ];
    }
}

// Register in EventServiceProvider
protected $subscribe = [
    InstructorEventSubscriber::class,
];

Common Use Cases¶

Logging and Monitoring¶

All events carry data in the $data property (typically an array). Use the name() method to get the event class short name.

use Cognesy\Instructor\Events\Extraction\ExtractionCompleted;
use Cognesy\Instructor\Events\Extraction\ExtractionFailed;
use Illuminate\Support\Facades\Log;

Event::listen(ExtractionCompleted::class, function ($event) {
    Log::channel('llm')->info('Extraction successful', [
        'event' => $event->name(),
        'data' => $event->data,
    ]);
});

Event::listen(ExtractionFailed::class, function ($event) {
    Log::channel('llm')->error('Extraction failed', [
        'event' => $event->name(),
        'data' => $event->data,
    ]);
});

Metrics and Analytics¶

use Cognesy\Instructor\Events\Extraction\ExtractionCompleted;
use App\Services\MetricsService;

Event::listen(ExtractionCompleted::class, function ($event) {
    app(MetricsService::class)->recordExtraction([
        'event' => $event->name(),
        'data' => $event->data,
    ]);
});

Alerting on Failures¶

use Cognesy\Instructor\Events\Extraction\ExtractionFailed;
use Illuminate\Support\Facades\Notification;
use App\Notifications\ExtractionFailedNotification;

Event::listen(ExtractionFailed::class, function ($event) {
    Notification::route('slack', config('services.slack.webhook'))
        ->notify(new ExtractionFailedNotification($event));
});

Queued Event Listeners¶

For CPU-intensive or I/O-heavy processing, implement ShouldQueue to push the work onto a queue instead of running it inline.

// app/Listeners/ProcessExtractionAnalytics.php
namespace App\Listeners;

use Cognesy\Instructor\Events\Extraction\ExtractionCompleted;
use Illuminate\Contracts\Queue\ShouldQueue;

class ProcessExtractionAnalytics implements ShouldQueue
{
    public $queue = 'analytics';

    public function handle(ExtractionCompleted $event): void
    {
        // Heavy analytics processing runs on the queue
    }
}

Wiretap (Direct Event Handling)¶

The wiretap method provides direct access to the raw event stream without going through Laravel's dispatcher. This is useful for low-level debugging or when you need to observe every internal event.

use Cognesy\Instructor\Laravel\Facades\StructuredOutput;
use Cognesy\Instructor\StructuredOutputRuntime;
use Cognesy\Polyglot\Inference\LLMProvider;

$runtime = StructuredOutputRuntime::fromProvider(LLMProvider::new())
    ->wiretap(function ($event) {
        // Called for every event in the pipeline
        logger()->debug('Event: ' . get_class($event));
    });

$person = StructuredOutput::withRuntime($runtime)->with(
    messages: 'Extract person data...',
    responseModel: PersonData::class,
)
->get();

The LaravelEventDispatcher itself also supports wiretap for registering global listeners that receive every event, regardless of class. These listeners run at the lowest priority after all class-specific and bridged listeners have executed.

Disabling Event Bridge¶

To disable event bridging entirely (for example, in high-throughput scenarios where the overhead is unacceptable):

// config/instructor.php
'events' => [
    'dispatch_to_laravel' => false,
],

Or via environment variable:

INSTRUCTOR_DISPATCH_EVENTS=false

Disabling the bridge only stops events from being forwarded to Laravel's dispatcher. Internal Instructor event listeners and wiretaps continue to work normally.

Testing Events¶

Use Laravel's Event::fake() to assert that specific events were dispatched during a test.

use Cognesy\Instructor\Events\Extraction\ExtractionCompleted;
use Illuminate\Support\Facades\Event;

public function test_dispatches_extraction_event(): void
{
    Event::fake([ExtractionCompleted::class]);

    StructuredOutput::with(
        messages: 'John is 30',
        responseModel: PersonData::class,
    )->get();

    Event::assertDispatched(ExtractionCompleted::class);
}

Assert event data with a closure:

Event::assertDispatched(ExtractionCompleted::class, function ($event) {
    return !empty($event->data);
});