​

Instructor for Laravel

​

Overview

• Laravel Facades — Use StructuredOutput::, Inference::, Embeddings::, and AgentCtrl:: facades for expressive, framework-native access to LLM capabilities.
• Dependency Injection — Inject StructuredOutput, Inference, or Embeddings directly into your classes through Laravel’s service container.
• Testing Fakes — Mock LLM responses with StructuredOutput::fake(), Inference::fake(), Embeddings::fake(), and AgentCtrl::fake(), complete with assertion helpers for verifying extraction calls, connection usage, and model selection.
• Native Agent Runtime — Resolve native Cognesy\Agents registries, loop factories, session runtime, broadcasting helpers, and telemetry wiring directly from Laravel’s container.
• Laravel HTTP Client — All API calls go through Laravel’s Http:: client under the hood, which means Http::fake() works out of the box in your test suite.
• Event Bridge — Instructor’s internal events are automatically dispatched through Laravel’s event system, so you can attach listeners, subscribers, and queued handlers with no extra wiring.
• Batteries Included Observability — Native agent broadcasting, telemetry projectors, and Laravel logging presets are wired through first-party config instead of app-local glue.
• Artisan Commands — Generate response model scaffolding with make:response-model, verify your API configuration with instructor:test, and bootstrap the package with instructor:install.
• Configuration Publishing — Laravel-style config file with environment variable support for all settings, from API keys and model selection to HTTP timeouts and logging presets.

• native Cognesy\Agents runtime integration under config('instructor.agents')
• external CLI code agents via AgentCtrl under config('instructor.agent_ctrl')

​

Quick Start

​

1. Install the Package

composer require cognesy/instructor-laravel
# @doctest id="c954"

​

2. Configure API Key

OPENAI_API_KEY=your-openai-api-key
// @doctest id="2ff4"

​

3. Extract Structured Data

use Cognesy\Instructor\Laravel\Facades\StructuredOutput;

// Define a response model
final class PersonData
{
    public function __construct(
        public readonly string $name,
        public readonly int $age,
    ) {}
}

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

echo $person->name; // "John Smith"
echo $person->age;  // 30
// @doctest id="9e13"

​

Documentation

​

Example: Complete Workflow

use Cognesy\Instructor\Laravel\Facades\StructuredOutput;
use App\ResponseModels\InvoiceData;

class InvoiceProcessor
{
    public function extractFromEmail(string $emailBody): InvoiceData
    {
        return StructuredOutput::with(
            messages: $emailBody,
            responseModel: InvoiceData::class,
            system: 'Extract invoice details from the email.',
        )->get();
    }
}

// In your test
public function test_extracts_invoice_data(): void
{
    $fake = StructuredOutput::fake([
        InvoiceData::class => new InvoiceData(
            invoiceNumber: 'INV-001',
            amount: 150.00,
            dueDate: '2024-12-31',
        ),
    ]);

    $processor = new InvoiceProcessor();
    $invoice = $processor->extractFromEmail('Invoice #INV-001...');

    $this->assertEquals('INV-001', $invoice->invoiceNumber);
    $fake->assertExtracted(InvoiceData::class);
}
// @doctest id="9bf8"

​

Requirements

• PHP 8.2+
• Laravel 10.x, 11.x, or 12.x

​

Support

• GitHub Issues
• Documentation