Skip to main 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

AgentDescription
Claude CodeAnthropic’s Claude agent with code execution
CodexOpenAI’s Codex agent
OpenCodeMulti-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:
DriverDescription
hostDirect execution (development)
dockerDocker container isolation
podmanRootless container isolation
firejailLinux sandbox
bubblewrapMinimal 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