Prism Documentation

Prism supports image moderation using models like omni-moderation-latest. You can provide images via the Image value object.

Important: Mixed Text and Image Behavior When mixing text and images in a single withInput() call:

• Multiple text inputs alone return multiple results (one per text).
• Multiple images alone return multiple results (one per image).
• Text + Image combinations return one result per image, where the text is treated as context/description for that specific image, not as a separate moderation target.

To get separate results for text and images, perform separate API calls.

use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;
use Prism\Prism\ValueObjects\Media\Image;

// Mixed text and images as variadic arguments
$response = Prism::moderation()
    ->using(Provider::OpenAI, 'omni-moderation-latest')
    ->withInput(
        'Check this text',
        Image::fromUrl('https://example.com/image.png'),
        'Another text to check',
        Image::fromLocalPath('/path/to/image1.jpg')
    )
    ->asModeration();

Prism distinguishes between whether a field must be present in the data structure and whether it can contain a null value.

Key Concepts

• Required Fields: Specified at the ObjectSchema level using requiredFields. A required field must be present in the data.
• Nullable Fields: Specified at the individual field level using nullable: true. A nullable field can contain a null value.

Common Patterns

OpenAI Strict Mode Requirement

When using OpenAI in strict mode, all fields must be marked as required. To make a field optional in this mode, you must mark it as both required in the ObjectSchema and nullable: true in the field schema.

// For OpenAI strict mode: 
// - All fields should be required
// - Use nullable: true for optional fields
$userSchema = new ObjectSchema(
    name: 'user',
    description: 'User profile',
    properties: [
        new StringSchema('email', 'Required email address'),
        new StringSchema('bio', 'Optional biography', nullable: true),
    ],
    requiredFields: ['email', 'bio'] // Note: bio is required but nullable
);

You can combine structured output with tools to allow the AI to gather information (via function calls) before formatting the final result into your schema.

Critical Requirement: When using tools with structured output, you must set withMaxSteps() to at least 2. The AI requires one step to call the tools and a subsequent step to return the final structured result.

Response Lifecycle: Only the final step in the sequence contains the structured data. Intermediate steps contain toolCalls and toolResults but no structured output.

use Prism\Prism\Facades\Prism;
use Prism\Prism\Schema\ObjectSchema;
use Prism\Prism\Schema\StringSchema;
use Prism\Prism\Tool;

$schema = new ObjectSchema(
    name: 'weather_analysis',
    description: 'Analysis of weather conditions',
    properties: [
        new StringSchema('summary', 'Summary of the weather'),
        new StringSchema('recommendation', 'Recommendation based on weather'),
    ],
    requiredFields: ['summary', 'recommendation']
);

$weatherTool = Tool::as('get_weather')
    ->for('Get current weather for a location')
    ->withStringParameter('location', 'The city and state')
    ->using(fn (string $location): string =>
        "Weather in {$location}: 72°F, sunny"
    );

$response = Prism::structured()
    ->using('anthropic', 'claude-3-5-sonnet-latest')
    ->withSchema($schema)
    ->withTools([$weatherTool])
    ->withMaxSteps(3)
    ->withPrompt('What is the weather in San Francisco and should I wear a coat?')
    ->asStructured();

// Access structured output
dump($response->structured);
// ['summary' => '...', 'recommendation' => '...']

Prism uses Anthropic's native structured outputs by default. This provides guaranteed schema compliance through constrained decoding without requiring a beta header.

Benefits:

• Always valid JSON
• Type safe

Limitations:

• Only available on Claude Sonnet 4.5+ and Claude Opus 4.1+
• Cannot be used with citations
• Certain JSON Schema features are not supported (e.g., recursive schemas, numerical/string constraints, complex regex).

Supported Schema Features:

• Basic types: object, array, string, integer, number, boolean, null
• enum for simple types
• anyOf and allOf (with limitations)
• required and additionalProperties: false
• String formats: date-time, email, uri, uuid, etc.

use Prism\Prism\Enums\Provider;
use Prism\Prism\Facades\Prism;
use Prism\Prism\Schema\ObjectSchema;
use Prism\Prism\Schema\StringSchema;

$response = Prism::structured()
    ->withSchema(new ObjectSchema(
        'weather_report',
        'Weather forecast with recommendations',
        [
            new StringSchema('forecast', 'The weather forecast'),
            new StringSchema('recommendation', 'Clothing recommendation')
        ],
        ['forecast', 'recommendation']
    ))
    ->using(Provider::Anthropic, 'claude-sonnet-4-5-20250929')
    ->withPrompt('What\'s the weather like and what should I wear?')
    ->asStructured();