README

A PHP package for easily working with OpenAI's structured output feature. This package provides a simple and intuitive way to define JSON schemas for OpenAI API calls and process the structured responses.

Features

Simple client for making OpenAI API calls with structured output
Fluent interface for building JSON schemas
Pre-built schema types for common use cases
Type-safe PHP classes with proper documentation

Installation

Install via Composer:

composer require omarsabbagh/php-openai-structured

Basic Usage

<?php

require 'vendor/autoload.php';

use Omarsabbagh\PhpOpenaiStructured\Client;
use Omarsabbagh\PhpOpenaiStructured\Schema\CategorizationSchema;

// Create a client with your API key
$client = new Client('your-openai-api-key');

// Create a categorization schema
$schema = new CategorizationSchema('contact_categorization', ['Real', 'Fake']);

// Define the system prompt
$systemPrompt = "
You are an AI model trained to categorize contact information into 'Real' or 'Fake'.
Analyze the given JSON-structured contact details and classify them accordingly.
";

// Input data to categorize
$input = [
    "first_name" => "John",
    "last_name" => "Smith",
    "email" => "jsmith@example.com"
];

// Get the categorization result
$result = $client->completeWithSchema($schema, $systemPrompt, $input);

// Use the structured result
echo "Category: " . $result['category'] . "\n";
echo "Reason: " . $result['reason'] . "\n";

Building Custom Schemas

You can build custom schemas for more complex use cases:

<?php

use Omarsabbagh\PhpOpenaiStructured\Schema\ObjectSchema;

// Create a custom schema
$schema = new ObjectSchema('entity_extraction');

// Add properties to the schema
$schema->addArrayProperty(
    'people',
    [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string', 'description' => 'Full name'],
            'role' => ['type' => 'string', 'description' => 'Role or occupation'],
        ],
        'required' => ['name']
    ],
    'List of people mentioned in the text',
    true
);

// Add more properties as needed...

Available Schema Types

CategorizationSchema

For categorizing input into predefined categories:

$schema = new CategorizationSchema('name', ['Category1', 'Category2']);

ObjectSchema

For creating custom object schemas:

$schema = new ObjectSchema('name');
$schema->addProperty('property', 'string', 'Description', true);
$schema->addEnumProperty('status', ['active', 'inactive'], 'Status description', true);
$schema->setAdditionalProperties(false);

Creating Your Own Schema Types

You can create your own schema types by extending the BaseSchema class:

class MyCustomSchema extends BaseSchema
{
    protected function getSchemaDefinition(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                // Your custom properties here
            ],
            'required' => ['property1', 'property2'],
            'additionalProperties' => false
        ];
    }
}

Examples

Check the examples directory for more examples of how to use this package:

examples/categorization.php - Basic categorization example
examples/custom_schema.php - Custom schema for entity extraction

Development

Running Tests

This package includes a comprehensive test suite. To run the tests:

composer install
vendor/bin/phpunit

The test suite includes:

Unit Tests: Tests for individual components
Integration Tests: Tests for components working together

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the project
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Requirements

PHP 8.1 or higher
OpenAI API key
Composer for dependency management

License

MIT License

omarsabbagh / php-openai-structured

Maintainers

Details