Packages

Start Here

Most PHP developers need just one package:

composer require cognesy/instructor-struct

This gives you everything: structured output extraction, validation, retries, and support for all major LLM providers. You’re ready to go.

When You Need More Control

Instructor is built on a modular architecture. If you need to work at a lower level or integrate with specific frameworks, these packages are available separately.

The Stack

Package Details

Instructor

The main package. Start here. Structured data extraction powered by LLMs. Define a PHP class with typed properties, pass it to Instructor with some text, get a validated object back.

<?php
class Person {
    public string $name;
    public int $age;
}

$person = (new StructuredOutput)
    ->withResponseClass(Person::class)
    ->withMessages("John is 25 years old")
    ->get();

// $person->name = "John"
// $person->age = 25

Why use it:

Type-safe outputs (your IDE understands the response)
Automatic validation with Symfony Validator
Self-correcting retries (LLM gets feedback on errors)
Works with any provider through Polyglot

→ Instructor Documentation

Polyglot

Use this when you need direct LLM access without structured extraction. A unified interface for LLM providers. Write code once, run it against any provider. Useful when you’re building chat interfaces, agents, or need raw completions.

<?php
$response = (new LLM)->using('anthropic')->chat("Explain PHP generators");

// Switch providers with one line
$response = (new LLM)->using('openai')->chat("Explain PHP generators");
$response = (new LLM)->using('gemini')->chat("Explain PHP generators");

Why use it:

Same code works with 20+ providers
No vendor lock-in
Streaming, embeddings, tool calling
Test with cheap/fast models, deploy with powerful ones

→ Polyglot Documentation

HTTP Client

Use this when you need low-level HTTP control. The HTTP layer that powers Polyglot. Most developers never touch this directly, but it’s available if you need custom HTTP handling, middleware, or want to build your own LLM integrations.

<?php
$client = new HttpClient();
$response = $client->handle($request);

// Streaming responses
foreach ($client->stream($request) as $chunk) {
    echo $chunk;
}

Why use it:

Streaming-first design
Middleware pipeline
Multiple backends
Single-request transport only

→ HTTP Client Documentation

HTTP Pool

Use this when you need concurrent request execution. http-pool handles fan-out workloads. It uses the same request and response objects as http-client, but the execution model is separate and focused on batching.

<?php
$pool = HttpPool::default();
$responses = $pool->pool($requests, maxConcurrent: 4);

Why use it:

Concurrent request execution
Typed request and response collections
Separate from single-request transport

→ HTTP Pool Documentation

Laravel Integration

Use this if you’re building with Laravel. Adds Laravel-specific conveniences: service provider, facades, config publishing, and testing fakes.

<?php
// Use the facade
use Cognesy\Instructor\Laravel\Facades\StructuredOutput;

$person = StructuredOutput::using('openai')
    ->with(
        messages: $text,
        responseModel: Person::class,
    )->get();

<?php
// Or inject via dependency injection
class PersonController
{
    public function extract(\Cognesy\Instructor\StructuredOutput $instructor)
    {
        return $instructor
            ->with(messages: $text, responseModel: Person::class)
            ->get();
    }
}

Why use it:

Auto-discovery (just install and use)
Laravel-style configuration
Testing fakes for unit tests
Integrates with Laravel’s logging

→ Laravel Documentation

Symfony Integration

Use this if you’re building with Symfony. Adds a first-party bundle surface for config translation, framework-owned event delivery, telemetry, logging, Messenger handoff, and package-aligned testing seams.

<?php

use Cognesy\Polyglot\Inference\Inference;

final readonly class SummarizeController
{
    public function __construct(
        private Inference $inference,
    ) {}

    public function __invoke(): array
    {
        return [
            'summary' => $this->inference
                ->withMessages('Summarize the current support ticket in one sentence.')
                ->get(),
        ];
    }
}

Why use it:

one instructor config root instead of scattered Symfony glue
package-owned event, delivery, telemetry, and logging wiring
AgentCtrl and native-agent seams that work in HTTP, Messenger, and CLI contexts
documented testing and migration path

→ Symfony Documentation

Internal Packages

These packages are used internally by Instructor and Polyglot. They’re not meant for direct use, but they’re available if you’re extending the library or curious about the architecture.

Package	Purpose
`addons`	Optional extensions (image handling, web scraping, agents)
`schema`	PHP class → JSON Schema conversion
`messages`	Message/conversation handling
`events`	Internal event system
`config`	Configuration management
`evals`	LLM evaluation tools
`metrics`	Usage tracking and observability
`templates`	Prompt templating
`stream`	Stream processing utilities

Quick Decision Guide

I want to…	Use this
Extract structured data from text	Instructor
Extract data from images	Instructor
Build a chatbot or agent	Polyglot
Switch between LLM providers easily	Polyglot (or Instructor, which includes it)
Use Instructor in Laravel	Instructor + Laravel package
Use Instructor in Symfony	Instructor + Symfony package
Build custom LLM integrations	HTTP Client + Polyglot
Just get started quickly	Instructor (includes everything)

Installation

# Most developers - get everything
composer require cognesy/instructor-struct

# Direct LLM access only (no structured extraction)
composer require cognesy/polyglot

# Laravel integration
composer require cognesy/instructor-laravel

# Symfony integration
composer require cognesy/instructor-symfony

# Low-level HTTP only
composer require cognesy/http-client

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

Packages

Start Here

When You Need More Control

The Stack

Package Details

Instructor

Polyglot

HTTP Client

HTTP Pool

Laravel Integration

Symfony Integration

Internal Packages

Quick Decision Guide

Installation

​Start Here

​When You Need More Control

​The Stack

​Package Details

​Instructor

​Polyglot

​HTTP Client

​HTTP Pool

​Laravel Integration

​Symfony Integration

​Internal Packages

​Quick Decision Guide

​Installation

Start Here

When You Need More Control

The Stack

Package Details

Instructor

Polyglot

HTTP Client

HTTP Pool

Laravel Integration

Symfony Integration

Internal Packages

Quick Decision Guide

Installation