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

<img src="https://mintcdn.com/cognesy-093fe941/Ua1nyfdh1K_-EfSm/images/instructor-diagram.png?fit=max&auto=format&n=Ua1nyfdh1K_-EfSm&q=85&s=fdb216d82c9c5d037882ab50ab54538f" alt="Instructor Stack" width="413" height="558" data-path="images/instructor-diagram.png" />

***

## 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**](/packages/instructor/introduction)

***

### 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**](/packages/polyglot/overview)

***

### 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**](/packages/http/1-overview)

***

### 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**](/packages/http/6-pooling)

***

### 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**](/packages/laravel/installation)

***

### 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**](/packages/symfony/overview)

***

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