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

# Packages

## Start Here

**Most PHP developers need just one package:**

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

![Instructor Stack](https://mintcdn.com/cognesy-093fe941/Ua1nyfdh1K_-EfSm/images/instructor-diagram.png?fit=max\&auto=format\&n=Ua1nyfdh1K_-EfSm\&q=85\&s=fdb216d82c9c5d037882ab50ab54538f)

***

## 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 theme={null}
<?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**](https://docs.instructorphp.com/packages/instructor/introduction.md)

***

### 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 theme={null}
<?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**](https://docs.instructorphp.com/packages/polyglot/overview.md)

***

### 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 theme={null}
<?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**](https://docs.instructorphp.com/packages/http/1-overview.md)

***

### 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 theme={null}
<?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**](https://docs.instructorphp.com/packages/http/6-pooling.md)

***

### Laravel Integration

**Use this if you're building with Laravel.**

Adds Laravel-specific conveniences: service provider, facades, config publishing, and testing fakes.

```php theme={null}
<?php
// Use the facade
use Cognesy\Instructor\Laravel\Facades\StructuredOutput;

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

```php theme={null}
<?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**](https://docs.instructorphp.com/packages/laravel/installation.md)

***

### 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 theme={null}
<?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**](https://docs.instructorphp.com/packages/symfony/overview.md)

***

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.