Skip to content

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
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(fn($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: 1. Continue using Instructor directly via dependency injection 2. Adopt facades gradually where convenient 3. Use ::fake() pattern for new tests

  1. Install the package
  2. Replace Http::fake() based tests with StructuredOutput::fake()
  3. Adopt facades in new code for cleaner syntax
  4. 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