neuron-structured-output

name

neuron-structured-output

description

Design and implement structured output classes for Neuron AI agents using SchemaProperty attributes and validation rules. Use this skill when the user mentions structured output, JSON schema extraction, data validation, output classes, DTOs for AI responses, extracting structured data from LLM, or configuring property schemas. Also trigger for any task involving SchemaProperty attribute, validation rules like NotBlank/Email/Url, nested objects, arrays of objects, enums, polymorphic types with anyOf, or the Validator class.

Neuron AI Structured Output

This skill helps you create structured output classes for extracting typed data from LLM responses in Neuron AI applications.

Core Concept

Neuron AI uses a two-layer approach for structured output:

1. SchemaProperty - Controls the JSON schema sent to the LLM to guide generation
2. Validation Rules - Verifies the LLM response meets your requirements

use NeuronAI\StructuredOutput\SchemaProperty;
use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;

class Person
{
    #[SchemaProperty(description: 'The user name.', required: true)]
    #[NotBlank]
    public string $name;
}

SchemaProperty Attribute

The SchemaProperty attribute defines how properties are represented in the JSON schema sent to the LLM.

Constructor Arguments

#[SchemaProperty(
    string $title = null,        // Property title in JSON schema
    string $description = null,  // Property description (guides LLM)
    bool $required = null,       // Override required status
    int $min = null,             // Minimum value (numbers) or items (arrays)
    int $max = null,             // Maximum value (numbers) or items (arrays)
    int $minLength = null,       // Minimum string length
    int $maxLength = null,       // Maximum string length
    array $anyOf = null,         // Array of allowed class/enum types
)]

Argument Implications

Argument	JSON Schema Output	Usage
title	title: "..."	Human-readable property title
description	description: "..."	Critical: Guides LLM on what to generate
required: true	Adds to required array	Property must be present
required: false	Excludes from required	Property is optional
min	minimum (numbers) or minItems (arrays)	Lower bound constraint
max	maximum (numbers) or maxItems (arrays)	Upper bound constraint
minLength	minLength	Minimum string characters
maxLength	maxLength	Maximum string characters
anyOf	anyOf: [...]	Polymorphic types (multiple possible classes)

Required Property Logic

Properties are required by default unless:

• required: false is explicitly set in SchemaProperty
• Property is nullable (?string $name)
• Property has a default value (string $name = 'default')

class Example
{
    // Required - non-nullable, no default
    public string $firstName;

    // Optional - explicitly marked
    #[SchemaProperty(required: false)]
    public string $middleName;

    // Optional - nullable
    public ?string $lastName;

    // Optional - has default
    public string $country = 'US';
}

Basic Property Types

String Properties

class Article
{
    #[SchemaProperty(
        description: 'The article title',
        minLength: 10,
        maxLength: 200
    )]
    public string $title;

    #[SchemaProperty(description: 'Article content')]
    public string $content;
}

Generated schema:

{
  "title": {
    "description": "The article title",
    "type": "string",
    "minLength": 10,
    "maxLength": 200
  },
  "content": {
    "description": "Article content",
    "type": "string"
  }
}

Numeric Properties

class Rating
{
    #[SchemaProperty(
        description: 'Rating from 1 to 5 stars',
        min: 1,
        max: 5
    )]
    public int $stars;

    #[SchemaProperty(description: 'Price in dollars')]
    public float $price;
}

Generated schema:

{
  "stars": {
    "description": "Rating from 1 to 5 stars",
    "type": "integer",
    "minimum": 1,
    "maximum": 5
  },
  "price": {
    "description": "Price in dollars",
    "type": "number"
  }
}

Boolean Properties

class Settings
{
    #[SchemaProperty(description: 'Whether notifications are enabled')]
    public bool $notificationsEnabled;
}

Nested Objects

Define nested classes to create complex structures:

use NeuronAI\StructuredOutput\SchemaProperty;
use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;

class Address
{
    #[SchemaProperty(description: 'The street name')]
    #[NotBlank]
    public string $street;

    public string $city;

    #[SchemaProperty(description: 'Postal/ZIP code')]
    public string $zip;
}

class Person
{
    #[NotBlank]
    public string $firstName;

    public string $lastName;

    // Nested object - type hint defines the schema
    public Address $address;
}

Usage:

$person = $agent->structured(
    new UserMessage('John Doe lives at 123 Main St, New York, 10001'),
    Person::class
);

echo $person->address->city; // "New York"

Arrays

Array of Strings (Simple)

class TagList
{
    #[SchemaProperty(description: 'List of tags', min: 1, max: 10)]
    public array $tags;
}

Array of Objects

Use anyOf to specify the object type for arrays:

use NeuronAI\StructuredOutput\Validation\Rules\ArrayOf;

class Tag
{
    #[SchemaProperty(description: 'The tag name')]
    public string $name;
}

class Article
{
    #[SchemaProperty(
        description: 'Article tags',
        anyOf: [Tag::class]
    )]
    #[ArrayOf(Tag::class)]
    public array $tags;
}

Important: Use both:

• SchemaProperty(anyOf: [Class::class]) - For JSON schema generation
• #[ArrayOf(Class::class)] - For validation

Nested Arrays (Deep Structures)

class TagProperty
{
    #[SchemaProperty(description: 'The property value')]
    public string $value;
}

class Tag
{
    #[SchemaProperty(description: 'Tag name')]
    public string $name;

    #[SchemaProperty(
        description: 'Additional tag properties',
        anyOf: [TagProperty::class]
    )]
    #[ArrayOf(TagProperty::class)]
    public array $properties;
}

class Person
{
    public string $name;

    #[SchemaProperty(anyOf: [Tag::class])]
    #[ArrayOf(Tag::class)]
    public array $tags;
}

Enums

Backed Enums (String or Int)

enum Status: string
{
    case ACTIVE = 'active';
    case INACTIVE = 'inactive';
    case PENDING = 'pending';
}

class User
{
    public string $name;

    // Enum type hint automatically generates enum schema
    public Status $status;
}

Generated schema:

{
  "status": {
    "type": "string",
    "enum": ["active", "inactive", "pending"]
  }
}

Integer Enums

enum Priority: int
{
    case LOW = 1;
    case MEDIUM = 2;
    case HIGH = 3;
}

class Task
{
    public string $title;
    public Priority $priority;
}

Polymorphic Types (anyOf)

Use anyOf when a property can be one of several types:

class FtpMode
{
    public string $mode;
    public string $account;
}

class EmailMode
{
    public string $mode;
    public string $mailingList;
}

class NotificationConfig
{
    #[SchemaProperty(anyOf: [FtpMode::class, EmailMode::class])]
    public array $modes;
}

Discriminator Field

For polymorphic arrays, Neuron uses a __classname__ discriminator field:

Generated schema includes:

{
  "modes": {
    "type": "array",
    "items": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "__classname__": {
              "type": "string",
              "enum": ["ftpmode"],
              "description": "This property is mandatory..."
            },
            "mode": {"type": "string"},
            "account": {"type": "string"}
          }
        },
        {
          "type": "object",
          "properties": {
            "__classname__": {
              "type": "string",
              "enum": ["emailmode"]
            },
            "mode": {"type": "string"},
            "mailingList": {"type": "string"}
          }
        }
      ]
    }
  }
}

The LLM must include __classname__ in responses for proper deserialization.

Validation Rules

Validation rules verify LLM output. If validation fails, Neuron can retry the request.

String Validation

use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;
use NeuronAI\StructuredOutput\Validation\Rules\Length;
use NeuronAI\StructuredOutput\Validation\Rules\Email;
use NeuronAI\StructuredOutput\Validation\Rules\Url;
use NeuronAI\StructuredOutput\Validation\Rules\WordsCount;

class UserProfile
{
    #[NotBlank]  // Cannot be empty or whitespace only
    public string $username;

    #[Email]
    public string $email;

    #[Url]
    public string $website;

    #[Length(min: 10, max: 500)]
    public string $bio;

    #[WordsCount(min: 5, max: 100)]
    public string $summary;

    #[Length(exactly: 10)]  // Must be exactly 10 characters
    public string $code;
}

Numeric Validation

use NeuronAI\StructuredOutput\Validation\Rules\GreaterThan;
use NeuronAI\StructuredOutput\Validation\Rules\LowerThan;
use NeuronAI\StructuredOutput\Validation\Rules\OutOfRange;
use NeuronAI\StructuredOutput\Validation\Rules\EqualTo;

class Product
{
    #[GreaterThan(0)]
    public float $price;

    #[LowerThan(1000)]
    public int $stock;

    #[OutOfRange(min: 0, max: 100)]  // Must be within range
    public int $discountPercentage;

    #[EqualTo(42)]
    public int $answer;
}

Array Validation

use NeuronAI\StructuredOutput\Validation\Rules\ArrayOf;
use NeuronAI\StructuredOutput\Validation\Rules\Count;

class Team
{
    #[ArrayOf(User::class)]
    public array $members;

    #[Count(min: 1, max: 10)]
    public array $tags;

    #[Count(exactly: 3)]
    public array $topThree;

    #[ArrayOf('string')]  // Array of scalar types
    public array $categories;
}

Boolean & Null Validation

use NeuronAI\StructuredOutput\Validation\Rules\IsTrue;
use NeuronAI\StructuredOutput\Validation\Rules\IsFalse;
use NeuronAI\StructuredOutput\Validation\Rules\IsNull;
use NeuronAI\StructuredOutput\Validation\Rules\IsNotNull;

class Settings
{
    #[IsTrue]
    public bool $agreedToTerms;

    #[IsFalse]
    public bool $isBlocked;

    #[IsNotNull]
    public ?string $optionalValue;
}

Enum Validation

use NeuronAI\StructuredOutput\Validation\Rules\Enum;

class Order
{
    // Validate against enum class
    #[Enum(class: Status::class)]
    public string $status;

    // Validate against explicit values
    #[Enum(values: ['urgent', 'normal', 'low'])]
    public string $priority;
}

Comparison Validation

use NeuronAI\StructuredOutput\Validation\Rules\EqualTo;
use NeuronAI\StructuredOutput\Validation\Rules\NotEqualTo;
use NeuronAI\StructuredOutput\Validation\Rules\GreaterThanEqual;
use NeuronAI\StructuredOutput\Validation\Rules\LowerThanEqual;

class Comparison
{
    #[EqualTo(100)]
    public int $exactValue;

    #[NotEqualTo(0)]
    public int $nonZero;

    #[GreaterThanEqual(1)]
    public int $atLeastOne;

    #[LowerThanEqual(10)]
    public int $atMostTen;
}

Format Validation

use NeuronAI\StructuredOutput\Validation\Rules\Email;
use NeuronAI\StructuredOutput\Validation\Rules\Url;
use NeuronAI\StructuredOutput\Validation\Rules\IPAddress;
use NeuronAI\StructuredOutput\Validation\Rules\Json;

class Contact
{
    #[Email]
    public string $email;

    #[Url]
    public string $website;

    #[IPAddress]
    public string $serverIp;

    #[Json]  // Must be valid JSON string
    public string $metadata;
}

Complete Validation Rules Reference

Rule	Description	Example
NotBlank	Not empty/whitespace	#[NotBlank(allowNull: true)]
Length	String length bounds	#[Length(min: 1, max: 100)]
WordsCount	Word count bounds	#[WordsCount(min: 5, max: 50)]
Email	Valid email format	#[Email]
Url	Valid URL format	#[Url]
IPAddress	Valid IP address	#[IPAddress]
Json	Valid JSON string	#[Json]
Enum	Value in allowed list	#[Enum(class: Status::class)]
ArrayOf	Array of specific type	#[ArrayOf(User::class)]
Count	Array item count	#[Count(min: 1, max: 10)]
GreaterThan	value > reference	#[GreaterThan(0)]
GreaterThanOrEqual	value >= reference	#[GreaterThanEqual(0)]
LowerThan	value < reference	#[LowerThan(100)]
LowerThanOrEqual	value <= reference	#[LowerThanEqual(100)]
OutOfRange	Value not in range	#[OutOfRange(min: 0, max: 100)]
EqualTo	Exact match	#[EqualTo(42)]
NotEqualTo	Not equal	#[NotEqualTo(0)]
IsTrue	Boolean true	#[IsTrue]
IsFalse	Boolean false	#[IsFalse]
IsNull	Must be null	#[IsNull]
IsNotNull	Must not be null	#[IsNotNull]

Usage with Agent

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;

// Define output class
class Person
{
    #[SchemaProperty(description: 'The person full name')]
    public string $name;

    #[SchemaProperty(description: 'What the person likes to eat')]
    public string $favoriteFood;

    #[SchemaProperty(description: 'Age in years', min: 0, max: 150)]
    public int $age;
}

// Use with agent
$agent = MyAgent::make();

$person = $agent->structured(
    new UserMessage("I'm John Doe, I'm 30 years old and I love pizza!"),
    Person::class
);

echo $person->name;          // "John Doe"
echo $person->age;           // 30
echo $person->favoriteFood;  // "pizza"

Manual Validation

use NeuronAI\StructuredOutput\Validation\Validator;

$person = new Person();
$person->name = '';
$person->age = -5;

$violations = Validator::validate($person);

if ($violations !== []) {
    foreach ($violations as $violation) {
        echo $violation . "\n";
    }
}

Manual Deserialization

use NeuronAI\StructuredOutput\Deserializer\Deserializer;

$json = '{"name": "John", "age": 30}';

$person = Deserializer::make()->fromJson($json, Person::class);

Default Values

Properties with default values are optional:

class Settings
{
    public string $theme = 'light';

    public int $timeout = 30;

    public bool $debug = false;
}

Generated schema includes defaults:

{
  "theme": {"type": "string", "default": "light"},
  "timeout": {"type": "integer", "default": 30},
  "debug": {"type": "boolean", "default": false}
}

DateTime Support

class Event
{
    public string $name;

    public DateTime $startDate;

    public DateTimeImmutable $createdAt;
}

Deserializer handles various date formats:

• ISO 8601 strings: "2024-01-15T10:30:00Z"
• Unix timestamps: 1705320600
• Relative formats: "next Monday"

Best Practices

1. Always Add Descriptions

// BAD - LLM doesn't know what to generate
public string $value;

// GOOD - Clear guidance for LLM
#[SchemaProperty(description: 'The monetary value in USD, must be positive')]
public float $value;

2. Use Validation for Critical Fields

class UserRegistration
{
    #[NotBlank]
    #[Email]
    public string $email;

    #[Length(min: 8, max: 64)]
    public string $password;

    #[NotBlank]
    public string $username;
}

3. Keep Schemas Focused

// BAD - Too many fields, harder for LLM
class UserProfile
{
    public string $name;
    public string $email;
    public string $phone;
    public string $address;
    public string $city;
    public string $country;
    public string $bio;
    public string $website;
    public string $company;
    public string $title;
    // ... 20 more fields
}

// GOOD - Focused on what you need
class UserContact
{
    public string $name;
    public string $email;
}

4. Use Enums for Fixed Options

// BAD - LLM might return unexpected values
#[SchemaProperty(description: 'Priority: low, medium, or high')]
public string $priority;

// GOOD - Constrained options
enum Priority: string
{
    case LOW = 'low';
    case MEDIUM = 'medium';
    case HIGH = 'high';
}

public Priority $priority;

5. Combine SchemaProperty and Validation

class Rating
{
    // Both guide LLM AND validate output
    #[SchemaProperty(description: 'Rating from 1 to 5', min: 1, max: 5)]
    #[GreaterThan(0)]
    #[LowerThan(6)]
    public int $stars;
}

Common Patterns

Contact Information

class Contact
{
    #[NotBlank]
    public string $name;

    #[Email]
    public string $email;

    #[Length(min: 10, max: 15)]
    public string $phone;
}

Address

class Address
{
    #[NotBlank]
    public string $street;

    #[NotBlank]
    public string $city;

    #[NotBlank]
    #[Length(exactly: 5)]
    public string $zipCode;

    public string $country;
}

Product

class Product
{
    #[NotBlank]
    public string $name;

    #[SchemaProperty(description: 'Price in USD', min: 0)]
    public float $price;

    #[Count(min: 1)]
    public array $categories;

    public bool $inStock;
}

Article with Tags

class Tag
{
    #[NotBlank]
    public string $name;
}

class Article
{
    #[NotBlank]
    public string $title;

    #[WordsCount(min: 50, max: 500)]
    public string $summary;

    #[SchemaProperty(anyOf: [Tag::class])]
    #[ArrayOf(Tag::class)]
    public array $tags;
}