Release Notes v1.14.0

New Package: instructor-laravel

Laravel Integration Package (packages/laravel/) A dedicated package providing first-class Laravel integration for Instructor PHP:

Facades

Four main facades for interacting with LLMs and code agents:

StructuredOutput:: - Extract structured data from text with validation and retries
Inference:: - Raw LLM inference without structured output constraints
Embeddings:: - Generate text embeddings for vector operations
AgentCtrl:: - Invoke CLI-based code agents (Claude Code, Codex, OpenCode)

use Cognesy\Instructor\Laravel\Facades\StructuredOutput;

$person = StructuredOutput::with(
    messages: 'John Smith is 30 years old',
    responseModel: PersonData::class,
)->get();

Testing Fakes

Laravel-style testing doubles with ::fake() pattern:

$fake = StructuredOutput::fake([
    PersonData::class => new PersonData(name: 'John', age: 30),
]);

// Your code runs...

$fake->assertExtracted(PersonData::class);
$fake->assertExtractedTimes(PersonData::class, 1);
$fake->assertUsedPreset('anthropic');

Available fakes:

StructuredOutput::fake() - Mock structured output responses
Inference::fake() - Mock inference responses with pattern matching
Embeddings::fake() - Mock embedding vectors
AgentCtrl::fake() - Mock code agent executions

Laravel HTTP Client Integration

Uses Laravel’s Http:: client internally, enabling:

Full compatibility with Http::fake() in tests
Request/response logging through Laravel’s HTTP middleware
Automatic retry handling via Laravel’s HTTP client features

Event Bridge

Instructor events are automatically dispatched to Laravel’s event system:

// In EventServiceProvider
class EventServiceProvider
{
    protected $listen = [
        \Cognesy\Events\Event::class => [
            MyInstructorEventListener::class,
        ],
    ];
}

Artisan Commands

php artisan instructor:install - Publish configuration and setup
php artisan instructor:test - Test your API configuration
php artisan make:response-model - Generate response model classes

Configuration

Laravel-style configuration with environment variables:

// config/instructor.php
return [
    'default' => env('INSTRUCTOR_CONNECTION', 'openai'),
    'connections' => [
        'openai' => [
            'driver' => 'openai',
            'api_key' => env('OPENAI_API_KEY'),
            'model' => env('OPENAI_MODEL', 'gpt-4o-mini'),
        ],
        'anthropic' => [
            'driver' => 'anthropic',
            'api_key' => env('ANTHROPIC_API_KEY'),
            'model' => env('ANTHROPIC_MODEL', 'claude-sonnet-4-20250514'),
        ],
    ],
];

New Feature: AgentCtrl Facade

Unified API for Controlling Agents The AgentCtrl facade provides access to CLI-based code agents that can execute code, modify files, and perform complex tasks:

Supported Agents

Agent	Description
Claude Code	Anthropic’s Claude agent with code execution
Codex	OpenAI’s Codex agent
OpenCode	Multi-model code agent with provider flexibility

Usage

use Cognesy\Instructor\Laravel\Facades\AgentCtrl;

// Execute with Claude Code
$response = AgentCtrl::claudeCode()
    ->withModel('claude-opus-4-5')
    ->inDirectory(base_path())
    ->withTimeout(300)
    ->execute('Generate a Laravel migration for users table');

if ($response->isSuccess()) {
    echo $response->text();
    echo "Cost: $" . $response->cost;
}

Streaming Support

$response = AgentCtrl::claudeCode()
    ->onText(function ($text) {
        echo $text;
    })
    ->onToolUse(fn($tool, $input, $output) => logger("Tool: $tool"))
    ->executeStreaming('Refactor the User model');

Session Management

// Start a session
$response = AgentCtrl::claudeCode()->execute('Start refactoring...');
$sessionId = $response->sessionId;

// Resume later
$response = AgentCtrl::claudeCode()
    ->resumeSession($sessionId)
    ->execute('Continue with the next file');

Testing

$fake = AgentCtrl::fake([
    'Generated migration successfully',
    'Created test file',
]);

// Your code runs...

$fake->assertExecuted();
$fake->assertUsedClaudeCode();
$fake->assertExecutedWith('migration');

Sandbox Drivers

Control agent execution isolation:

Driver	Description
`host`	Direct execution (development)
`docker`	Docker container isolation
`podman`	Rootless container isolation
`firejail`	Linux sandbox
`bubblewrap`	Minimal sandbox (CI/CD)

Installation

composer require cognesy/instructor-laravel

Add to your .env:

OPENAI_API_KEY=your-api-key

The package auto-discovers and registers itself with Laravel.

Migration Notes

For Existing Instructor Users

The Laravel package is additive - no changes required to existing code. You can:

Continue using Instructor directly via dependency injection
Adopt facades gradually where convenient
Use ::fake() pattern for new tests

Recommended Adoption Path

Install the package
Replace Http::fake() based tests with StructuredOutput::fake()
Adopt facades in new code for cleaner syntax
Migrate existing DI usage to facades where appropriate

Key Benefits

Laravel Integration: Facades, fakes, and configuration follow Laravel conventions
Testing: ::fake() pattern with comprehensive assertions
Zero Configuration: Works out of the box with sensible defaults
Event Integration: Full visibility into Instructor operations via Laravel events
Code Agents: Access powerful CLI agents directly from your Laravel application

Main

Release Notes

V1.14.0

Release Notes v1.14.0

New Package: instructor-laravel

Facades

Testing Fakes

Laravel HTTP Client Integration

Event Bridge

Artisan Commands

Configuration

New Feature: AgentCtrl Facade

Supported Agents

Usage

Streaming Support

Session Management

Testing

Sandbox Drivers

Installation

Migration Notes

For Existing Instructor Users

Recommended Adoption Path

Key Benefits

​Release Notes v1.14.0

​New Package: instructor-laravel

​Facades

​Testing Fakes

​Laravel HTTP Client Integration

​Event Bridge

​Artisan Commands

​Configuration

​New Feature: AgentCtrl Facade

​Supported Agents

​Usage

​Streaming Support

​Session Management

​Testing

​Sandbox Drivers

​Installation

​Migration Notes

​For Existing Instructor Users

​Recommended Adoption Path

​Key Benefits

Release Notes v1.14.0

New Package: instructor-laravel

Facades

Testing Fakes

Laravel HTTP Client Integration

Event Bridge

Artisan Commands

Configuration

New Feature: AgentCtrl Facade

Supported Agents

Usage

Streaming Support

Session Management

Testing

Sandbox Drivers

Installation

Migration Notes

For Existing Instructor Users

Recommended Adoption Path

Key Benefits