Structured Output

Atlas supports schema-based responses for extracting structured data from AI responses.

Prism Reference

Atlas uses Prism's schema system under the hood. For detailed schema documentation, see Prism Structured Output and Prism Schemas.

What is Structured Output?

Instead of free-form text, structured output returns data in a predefined format:

php

use Atlasphp\Atlas\Atlas;
use Atlasphp\Atlas\Schema\Schema;

$response = Atlas::agent('analyzer')
    ->withSchema(
        Schema::object('sentiment', 'Sentiment analysis result')
            ->enum('sentiment', 'The sentiment', ['positive', 'negative', 'neutral'])
            ->number('confidence', 'Confidence score from 0 to 1')
    )
    ->chat('I love this product!');

echo $response->structured['sentiment'];   // "positive"
echo $response->structured['confidence'];  // 0.95

Atlas Schema Builder

Atlas provides a fluent Schema Builder that creates Prism schemas with less boilerplate and automatic required field tracking.

Basic Usage

php

use Atlasphp\Atlas\Schema\Schema;

// Inline - auto-builds when passed to withSchema()
$response = Atlas::agent('extractor')
    ->withSchema(
        Schema::object('contact', 'Contact information')
            ->string('name', 'Full name')
            ->string('email', 'Email address')
            ->number('age', 'Age in years')
    )
    ->chat('Extract: John Smith, john@example.com, 30 years old');

// Or build separately for reuse
$schema = Schema::object('contact', 'Contact information')
    ->string('name', 'Full name')
    ->string('email', 'Email address')
    ->build();

The Schema Builder automatically tracks required fields and builds valid Prism schema objects. All fields are required by default, matching OpenAI's recommended practice.

Property Types

php

// String
->string('name', 'The person\'s full name')

// Number (float/decimal)
->number('score', 'A score between 0 and 100')

// Integer (alias for number)
->integer('count', 'Number of items')

// Boolean
->boolean('is_valid', 'Whether the input is valid')

// Enum
->enum('status', 'The current status', ['pending', 'approved', 'rejected'])

// String array
->stringArray('tags', 'List of relevant tags')

// Number array
->numberArray('scores', 'List of scores')

// Object array
->array('items', 'Order items', fn($s) => $s
    ->string('name', 'Item name')
    ->number('quantity', 'Quantity')
)

// Nested object
->object('address', 'Mailing address', fn($s) => $s
    ->string('street', 'Street address')
    ->string('city', 'City name')
)

Optional and Nullable Fields

php

Schema::object('user', 'User profile')
    ->string('name', 'Full name')                        // required
    ->string('email', 'Email address')                   // required
    ->string('phone', 'Phone number')->optional()        // NOT required
    ->string('notes', 'Optional notes')->nullable()      // NOT required + can be null
    ->build()

->optional() — Removes the field from required fields
->nullable() — Makes the field nullable (implies optional)

Using Prism Schemas Directly

Atlas accepts Prism schema objects directly. If you're already familiar with Prism or need advanced schema features, you can use Prism's schema classes:

php

use Atlasphp\Atlas\Atlas;
use Prism\Prism\Schema\ObjectSchema;
use Prism\Prism\Schema\NumberSchema;
use Prism\Prism\Schema\EnumSchema;

$schema = new ObjectSchema(
    name: 'sentiment',
    description: 'Sentiment analysis result',
    properties: [
        new EnumSchema('sentiment', 'The sentiment', ['positive', 'negative', 'neutral']),
        new NumberSchema('confidence', 'Confidence score from 0 to 1'),
    ],
    requiredFields: ['sentiment', 'confidence'],
);

$response = Atlas::agent('analyzer')
    ->withSchema($schema)
    ->chat('I love this product!');

Available Prism schema types:

StringSchema — Text values
NumberSchema — Integers and floats
BooleanSchema — True/false values
ArraySchema — Lists of items
EnumSchema — Predefined set of options
ObjectSchema — Nested structures