Download the PHP package brdv/forerunner without Composer

Forerunner - Build structured LLM outputs the Laravel way

A Laravel package that provides an elegant, migration-inspired API for defining JSON schemas that ensure your LLM responses are perfectly structured every time.

Installation

You can install the package via composer:

Note: This is a pre-release version (0.x). The API may change as we gather feedback and iterate towards 1.0.0.

The package will automatically register its service provider.

Upgrading from 0.1.x

If you're upgrading from version 0.1.x, please note there are breaking changes. See the v0.2.0 release notes for a complete migration guide.

Quick Start

Using the Artisan Command

Generate a new structure class:

This creates a structure class at app/Structures/UserProfile.php:

Basic Usage

Define a schema using the Struct class or Schema facade:

Or using the facade for a cleaner syntax:

Available Field Types

String Fields

Integer Fields

Float/Number Fields

Boolean Fields

Array Fields

Enum Fields

Object Fields

Field Constraints

String Constraints

Numeric Constraints

Array Constraints

General Constraints

Advanced Features

Helper Methods for Common Formats

Forerunner provides convenient helper methods for commonly used field formats:

String Format Validation

You can also set custom formats on string fields:

Supported formats: email, uri, url, uuid, date, date-time, time, ipv4, ipv6, hostname, and more.

Nullable Fields

Mark fields as nullable to allow both the specified type and null:

Unique Array Items

Ensure array items are unique:

Additional Properties Control

Control whether objects can have properties not defined in the schema:

Strict Mode for LLM APIs

The strict() method is particularly useful for LLM APIs like OpenAI Structured Outputs which require:

1. additionalProperties: false
2. All properties in the required array

Important: Call strict() after defining all your fields to ensure all of them are marked as required.

This generates:

Note: By default, additionalProperties is already set to false. Use strict() when you also need all fields to be required (like for OpenAI). Call it after defining fields to ensure all are marked as required.

Schema Metadata

Add metadata to your schemas:

You can also add titles to individual fields:

Complete Advanced Example

This generates:

Complex Examples

User Profile with Nested Objects

Blog Post with Comments

Working with Generated Schemas

The Struct::define() method returns a Struct object that can be converted to an array or JSON.

Convert to Array

JSON Serialization

The Struct object implements JsonSerializable, so you can use it directly with json_encode():

Using Structure Classes

When using the make:struct command, you can create reusable schema classes:

Testing

Run the test suite:

Run tests with coverage:

Code Quality

Run PHPStan analysis:

Format code with Laravel Pint:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Acknowledgements

This package is a fork of blaspsoft/forerunner, originally created by Blaspsoft. The original package is no longer maintained. Full credit for the initial design and implementation goes to the original authors.

Credits

• Bram
• Blaspsoft (original author)
• All Contributors

License

The MIT License (MIT). Please see License File for more information.