> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instructorphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# V1.14.0

# 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)

```php theme={null}
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:

```php theme={null}
$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:

```php theme={null}
// 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:

```php theme={null}
// 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

```php theme={null}
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

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

### Session Management

```php theme={null}
// 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

```php theme={null}
$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

```bash theme={null}
composer require cognesy/instructor-laravel
```

Add to your `.env`:

```env theme={null}
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

### Recommended Adoption Path

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