Prism

https://github.com/prism-php/prism
Admin
Prism is a powerful Laravel package for integrating Large Language Models (LLMs) into applications,...
Tokens:375,469
Snippets:2,692
Trust Score:6
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### AnyOfSchema usage with simple and complex examples

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/schemas.md

Shows how to create an AnyOfSchema with a simple string-or-number example and a complex example with different content types (article and image). Requires OpenAI or Gemini provider support; Anthropic does not support anyOf.

```php
use Prism\Prism\Schema\AnyOfSchema;
use Prism\Prism\Schema\StringSchema;
use Prism\Prism\Schema\NumberSchema;
use Prism\Prism\Schema\ObjectSchema;

// Simple example: A value that can be either a string or number
$flexibleValueSchema = new AnyOfSchema(
    schemas: [
        new StringSchema('text', 'A text value'),
        new NumberSchema('number', 'A numeric value'),
    ],
    name: 'flexible_value',
    description: 'A value that can be either text or numeric'
);

// Complex example: Different content types
$contentSchema = new AnyOfSchema(
    schemas: [
        new ObjectSchema(
            name: 'article',
            description: 'A blog article',
            properties: [
                new StringSchema('title', 'Article title'),
                new StringSchema('content', 'Article content'),
                new StringSchema('author', 'Article author'),
            ],
            requiredFields: ['title', 'content']
        ),
        new ObjectSchema(
            name: 'image',
            description: 'An image post',
            properties: [
                new StringSchema('url', 'Image URL'),
                new StringSchema('caption', 'Image caption'),
                new NumberSchema('width', 'Image width in pixels'),
                new NumberSchema('height', 'Image height in pixels'),
            ],
            requiredFields: ['url']
        ),
    ],
    name: 'content',
    description: 'Content that can be either an article or an image'
);
```

--------------------------------

### Basic Example: Weather Tool with Structured Output

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/structured-output.md

Creates a schema for weather analysis and a weather tool, then uses Prism::structured() with the Anthropic Claude model to get structured output. Requires maxSteps to be at least 2 when using tools.

```php
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' => '...']
```

--------------------------------

### Clear and Direct Example

Source: https://github.com/prism-php/prism/blob/main/docs/documentation-style-guide.md

Contrasts a passive, indirect recommendation with an active, direct instruction. Use the preferred version to get to the point quickly and use active voice.

```markdown
❌ "It is recommended that validation be implemented using the provided methods."
✅ "Validate your inputs using the validate() method."
```

--------------------------------

### Generate an image with Prism::image() and output URL

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/image-generation.md

Basic example from the 'Getting Started' section. Uses the 'openai' provider with the 'dall-e-3' model. The response's firstImage() method returns an image object whose url property is echoed. The output is a URL like https://oaidalleapiprodscus.blob.core.windows.net/...

```php
use Prism\Prism\Facades\Prism;

$response = Prism::image()
    ->using('openai', 'dall-e-3')
    ->withPrompt('A cute baby sea otter floating on its back in calm blue water')
    ->generate();

$image = $response->firstImage();
echo $image->url; // https://oaidalleapiprodscus.blob.core.windows.net/...
```

--------------------------------

### Environment variables example

Source: https://github.com/prism-php/prism/blob/main/docs/getting-started/configuration.md

Example .env file showing environment variables for Prism Server and provider configuration. Follows the naming pattern: PROVIDER_API_KEY, PROVIDER_URL, etc.

```shell
# Prism Server Configuration
PRISM_SERVER_ENABLED=true

# Provider Configuration
PROVIDER_API_KEY=your-api-key-here
PROVIDER_URL=https://custom-endpoint.com
```

--------------------------------

### Run documentation development server

Source: https://github.com/prism-php/prism/blob/main/docs/README.md

Starts the Vitepress development server for local documentation preview. Run from the project root.

```shell
npm run docs:dev
```

--------------------------------

### PHP Code Example with Basic and Advanced Usage

Source: https://github.com/prism-php/prism/blob/main/docs/documentation-style-guide.md

Demonstrates a basic Eloquent query and a more advanced version with additional constraints. Use the advanced example to filter users by active status and active subscriptions.

```php
// Basic Example
$users = User::where('active', true)
    ->orderBy('name')
    ->get();
// With Additional Constraints
$users = User::where('active', true)
    ->whereHas('subscriptions', function ($query) {
        $query->where('status', 'active');
    })
    ->orderBy('name')
    ->get();
```

--------------------------------

### Add video to prompt with Video value object

Source: https://github.com/prism-php/prism/blob/main/docs/input-modalities/video.md

Shows how to use `Prism::text()->withPrompt()` with a `Video` value object to include video content. The example demonstrates six ways to create a `Video`: from a local path, from a storage disk path, from a URL, from a YouTube URL (with automatic ID extraction), from a shortened YouTube URL, from base64 data, and from raw content. All examples use the Gemini provider with the 'gemini-1.5-flash' model.

```php
use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;
use Prism\Prism\ValueObjects\Media\Video;

// From a local path
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        "What's in this video?",
        [Video::fromLocalPath(path: '/path/to/video.mp4')]
    )
    ->asText();

// From a path on a storage disk
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        "What's in this video?",
        [Video::fromStoragePath(
            path: '/path/to/video.mp4',
            diskName: 'my-disk' // optional - omit/null for default disk
        )]
    )
    ->asText();

// From a URL
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        'Analyze this video:',
        [Video::fromUrl(url: 'https://example.com/video.mp4')]
    )
    ->asText();

// From a YouTube URL (automatically extracts the video ID)
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        'What is this YouTube video about?',
        [Video::fromUrl(url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ')]
    )
    ->asText();

// From shortened YouTube URL
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        'What is this YouTube video about?',
        [Video::fromUrl(url: 'https://youtu.be/dQw4w9WgXcQ')]
    )
    ->asText();

// From base64
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        'Analyze this video:',
        [Video::fromBase64(
            base64: base64_encode(file_get_contents('/path/to/video.mp4')),
            mimeType: 'video/mp4'
        )]
    )
    ->asText();

// From raw content
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        'Analyze this video:',
        [Video::fromRawContent(
            rawContent: file_get_contents('/path/to/video.mp4'),
            mimeType: 'video/mp4'
        )]
    )
    ->asText();
```

--------------------------------

### Using a Reasoning Model

Source: https://github.com/prism-php/prism/blob/main/docs/providers/mistral.md

Example of using a reasoning model (magistral-medium-latest) to get a response with thinking content automatically included.

```php
use Prism\Prism\Facades\Prism;

$response = Prism::text()
    ->using('mistral', 'magistral-medium-latest')
    ->withPrompt('What is the capital of France?')
    ->asText();

// Access the final answer
echo $response->text;
// "The capital of France is Paris."

// Access the reasoning process
echo $response->additionalContent['thinking'];
// "Okay, the user asked about the capital of France. I know that the capital of France is Paris..."
```

--------------------------------

### Install Prism via Composer

Source: https://github.com/prism-php/prism/blob/main/docs/getting-started/installation.md

Run this command in your terminal to add Prism to your project. It downloads Prism and its dependencies.

```bash
composer require prism-php/prism
```

--------------------------------

### Metadata Provider Option

Source: https://github.com/prism-php/prism/blob/main/docs/providers/openai.md

Attach metadata to the request using the 'metadata' provider option. Example sets a project_id of 23.

```php
$response = Prism::structured()
    ->withProviderOptions([ // [!code focus]
        'metadata' => [ // [!code focus]
            'project_id' => 23 // [!code focus]
        ] // [!code focus]
    ]) // [!code focus]
```

--------------------------------

### Tone Example: Introduction

Source: https://github.com/prism-php/prism/blob/main/docs/documentation-style-guide.md

Contrasts a formal, abstract introduction with a friendly, concrete one. Use the preferred version to engage the reader and outline what will be covered.

```markdown
❌ "This documentation delineates the methodologies for implementing the authentication system."
✅ "In this guide, you'll learn how to add authentication to your app. We'll cover everything from basic login forms to OAuth providers."
```

--------------------------------

### Source code reference commands

Source: https://github.com/prism-php/prism/blob/main/resources/boost/skills/developing-with-prism/SKILL.md

Use glob and grep to explore the source code, for example to find all PHP files and search for 'class Tool'.

```bash
glob "src/**/*.php"
grep "class Tool" src/
```

--------------------------------

### Combining Tools with Structured Output

Source: https://github.com/prism-php/prism/blob/main/docs/providers/openai.md

Complete example of using tools with structured output. Set maxSteps to at least 2; OpenAI uses the /responses endpoint and sets parallel_tool_calls: false.

```php
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('openai', 'gpt-4o')
    ->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);

// Access tool execution details
foreach ($response->toolCalls as $toolCall) {
    echo "Called: {$toolCall->name}\n";
}
```

--------------------------------

### Access Audio Properties (mimeType, hasLocalPath, size)

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/audio.md

Demonstrates how to retrieve MIME type, check for a local path, and get the file size of an Audio object.

```php
$audio = Audio::fromPath('/path/to/audio.mp3');

echo "MIME type: " . $audio->mimeType();
echo "Has local path: " . ($audio->hasLocalPath() ? 'Yes' : 'No');
echo "File size: " . $audio->size() . " bytes";
```

--------------------------------

### System Prompt with Prism

Source: https://github.com/prism-php/prism/blob/main/docs/public/storage/prism-text-generation.pdf

Sets a system prompt to define the AI's behavior and context. The example uses a simple string system prompt.

```php
use Prism\Prism\Prism;
use Prism\Prism\Enums\Provider;

$response = Prism::text()
->using(Provider::Anthropic, 'claude-3-5-sonnet-20241022')
->withSystemPrompt('You are an expert mathematician who explains concepts simply.')
->withPrompt('Explain the Pythagorean theorem.')
->asText();
```

--------------------------------

### Nested Organization Example

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/schemas.md

Shows how to define child schemas first and then use them in a parent schema for complex structures. This keeps schemas organized.

```php
// Define child schemas first
$addressSchema = new ObjectSchema(/*...*/);
$contactSchema = new ObjectSchema(/*...*/);

// Then use them in your parent schema
$userSchema = new ObjectSchema(
    name: 'user',
    description: 'Complete user profile',
    properties: [$addressSchema, $contactSchema]
);
```

--------------------------------

### Clear Descriptions Example

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/schemas.md

Shows the contrast between a non-helpful and a helpful description for a StringSchema field. Use clear, concise descriptions to aid future developers.

```php
// ❌ Not helpful
new StringSchema('name', 'the name');

// ✅ Much better
new StringSchema('name', 'The user\'s display name (2-50 characters)');
```

--------------------------------

### Read specific doc files

Source: https://github.com/prism-php/prism/blob/main/resources/boost/skills/developing-with-prism/SKILL.md

Use the read command to open specific documentation files. The example shows reading the text-generation and OpenAI provider docs.

```bash
read vendor/prism-php/prism/docs/core-concepts/text-generation.md
read vendor/prism-php/prism/docs/providers/openai.md
```

--------------------------------

### Callouts and Notes Example

Source: https://github.com/prism-php/prism/blob/main/docs/documentation-style-guide.md

Shows the syntax for GitHub-flavored markdown callouts: NOTE, TIP, IMPORTANT, WARNING, and CAUTION. Use these to highlight information with varying levels of importance.

```markdown
> [!NOTE]
> Highlights information that users should take into account, even when skimming.
> [!TIP]
> Optional information to help a user be more successful.
> [!IMPORTANT]
> Crucial information necessary for users to succeed.
> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.
> [!CAUTION]
> Negative potential consequences of an action.
```

--------------------------------

### Tone Example: Error Handling

Source: https://github.com/prism-php/prism/blob/main/docs/documentation-style-guide.md

Contrasts a formal recommendation with a friendly, action-oriented one. Use the preferred version to encourage robust error handling in a supportive way.

```markdown
❌ "Exception handling must be implemented to prevent application failure."
✅ "Let's make your app more robust by catching and handling potential errors gracefully."
```

--------------------------------

### Quick Start: Define schema and get structured output

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/structured-output.md

Defines an ObjectSchema with required string properties and uses Prism::structured() to get a structured response. Note: for OpenAI strict mode, the root schema must be an ObjectSchema.

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

$schema = new ObjectSchema(
    name: 'movie_review',
    description: 'A structured movie review',
    properties: [
        new StringSchema('title', 'The movie title'),
        new StringSchema('rating', 'Rating out of 5 stars'),
        new StringSchema('summary', 'Brief review summary')
    ],
    requiredFields: ['title', 'rating', 'summary']
);

$response = Prism::structured()
    ->using(Provider::OpenAI, 'gpt-4o')
    ->withSchema($schema)
    ->withPrompt('Review the movie Inception')
    ->asStructured();

// Access your structured data
$review = $response->structured;
echo $review['title'];    // "Inception"
echo $review['rating'];   // "5 stars"
echo $review['summary'];  // "A mind-bending..."
```

--------------------------------

### Basic Example: Combining Tools with Structured Output

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/tools-function-calling.md

Defines a schema for weather analysis, creates a 'get_weather' tool, and sends a structured request using Prism. Requires setting maxSteps to at least 2 when combining tools with structured output.

```php
use Prism\Prism\Facades\Prism;
use Prism\Prism\Schema\ObjectSchema;
use Prism\Prism\Schema\StringSchema;
use Prism\Prism\Facades\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();

// Response contains both structured data and tool execution details
dump($response->structured);
```

--------------------------------

### Vercel AI SDK Data Protocol Output

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/streaming-output.md

Example of the structured streaming data format emitted by the Vercel AI SDK, showing start, text-delta, finish, and [DONE] events.

```text
data: {"type":"start","messageId":"anthropic_evt_NPbGJs7D0oQhvz2K"}

data: {"type":"start-step"}

data: {"type":"text-start","id":"msg_013P3F8KkVG3Qasjeay3NUmY"}

data: {"type":"text-delta","id":"msg_013P3F8KkVG3Qasjeay3NUmY","delta":"Hello"}

data: {"type":"text-end","id":"msg_013P3F8KkVG3Qasjeay3NUmY"}

data: {"type":"finish-step"}

data: {"type":"finish","messageMetadata":{"finishReason":"stop","usage":{"promptTokens":1998,"completionTokens":288}}}

data: [DONE]
```

--------------------------------

### Response Formats for Groq STT

Source: https://github.com/prism-php/prism/blob/main/docs/providers/groq.md

Shows how to get transcriptions in different formats. 'json' is standard, 'verbose_json' includes timestamps and segments. The example also demonstrates accessing segment details from the response.

```php
// Standard JSON response
$response = Prism::audio()
    ->using('groq', 'whisper-large-v3')
    ->withInput($audioFile)
    ->withProviderOptions([
        'response_format' => 'json',  // json, text, verbose_json
    ])
    ->asText();

// Verbose JSON includes timestamps and segments
$response = Prism::audio()
    ->using('groq', 'whisper-large-v3')
    ->withInput($audioFile)
    ->withProviderOptions([
        'response_format' => 'verbose_json',
        'timestamp_granularities' => ['segment'], // word, segment
    ])
    ->asText();

// Access detailed segment information
$segments = $response->additionalContent['segments'] ?? [];
foreach ($segments as $segment) {
    echo "Text: " . $segment['text'] . "\n";
    echo "Start: " . $segment['start'] . "s\n";
    echo "End: " . $segment['end'] . "s\n";
}
```

--------------------------------

### Add audio with withPrompt using Audio value object

Source: https://github.com/prism-php/prism/blob/main/docs/input-modalities/audio.md

Shows five ways to attach audio to a prompt: from local path, storage disk, URL, base64, and raw content. Uses Gemini provider and the Audio value object.

```php
use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;
use Prism\Prism\ValueObjects\Media\Audio;

// From a local path
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        "What's in this audio?",
        [Audio::fromLocalPath(path: '/path/to/audio.mp3')]
    )
    ->asText();

// From a path on a storage disk
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        "What's in this audio?",
        [Audio::fromStoragePath(
            path: '/path/to/audio.mp3',
            diskName: 'my-disk' // optional - omit/null for default disk
        )]
    )
    ->asText();

// From a URL
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        'Analyze this audio:',
        [Audio::fromUrl(url: 'https://example.com/audio.mp3')]
    )
    ->asText();

// From base64
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        'Analyze this audio:',
        [Audio::fromBase64(
            base64: base64_encode(file_get_contents('/path/to/audio.mp3')),
            mimeType: 'audio/mpeg'
        )]
    )
    ->asText();

// From raw content
$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withPrompt(
        'Analyze this audio:',
        [Audio::fromRawContent(
            rawContent: file_get_contents('/path/to/audio.mp3'),
            mimeType: 'audio/mpeg'
        )]
    )
    ->asText();
```

--------------------------------

### Response Formats: JSON and Verbose JSON

Source: https://github.com/prism-php/prism/blob/main/docs/providers/openai.md

Shows how to get standard JSON or verbose JSON (with timestamps and confidence scores) transcriptions. The verbose JSON example also demonstrates accessing segment details.

```php
// Standard JSON response
$response = Prism::audio()
    ->using('openai', 'whisper-1')
    ->withInput($audioFile)
    ->withProviderOptions([
        'response_format' => 'json',  // json, text, srt, verbose_json, vtt
    ])
    ->asText();

// Verbose JSON includes timestamps and confidence scores
$response = Prism::audio()
    ->using('openai', 'whisper-1')
    ->withInput($audioFile)
    ->withProviderOptions([
        'response_format' => 'verbose_json',
    ])
    ->asText();

// Access detailed segment information
$segments = $response->additionalContent['segments'] ?? [];
foreach ($segments as $segment) {
    echo "Text: " . $segment['text'] . "\n";
    echo "Start: " . $segment['start'] . "s\n";
    echo "End: " . $segment['end'] . "s\n";
    echo "Confidence: " . ($segment['no_speech_prob'] ?? 'N/A') . "\n\n";
}
```

--------------------------------

### Build documentation for production

Source: https://github.com/prism-php/prism/blob/main/docs/README.md

Builds the documentation site for production deployment, typically used before deploying to Netlify.

```shell
npm run docs:build
```

--------------------------------

### Create Audio Objects from Path, URL, Base64, or Content

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/audio.md

Shows the four factory methods on the Audio class: fromPath, fromUrl, fromBase64, and fromContent. Use the appropriate method based on the source of your audio data.

```php
use Prism\Prism\ValueObjects\Media\Audio;

// From local file
$audio = Audio::fromPath('/path/to/audio.mp3');

// From remote URL
$audio = Audio::fromUrl('https://example.com/speech.wav');

// From base64 encoded data
$audio = Audio::fromBase64($base64Data, 'audio/mpeg');

// From raw binary content
$audio = Audio::fromContent($binaryData, 'audio/wav');
```

--------------------------------

### Required Fields Warning Example

Source: https://github.com/prism-php/prism/blob/main/docs/providers/openai.md

Example schema showing all fields listed in requiredFields, with optional fields marked as nullable. This is required for OpenAI structured outputs, especially in strict mode.

```php
new ObjectSchema(
    name: 'user',
    properties: [
        new StringSchema('email', 'Email address'),
        new StringSchema('bio', 'Optional bio', nullable: true),
    ],
    requiredFields: ['email', 'bio'] // ✅ All fields listed
);
```

--------------------------------

### Multiple Tools Example: Game Analysis

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/structured-output.md

Provides two tools (get_weather and search_games) to the AI, using OpenAI's GPT-4o model. Demonstrates using multiple tools with structured output and a higher maxSteps value.

```php
$schema = new ObjectSchema(
    name: 'game_analysis',
    description: 'Analysis of game time and weather',
    properties: [
        new StringSchema('game_time', 'The time of the game'),
        new StringSchema('weather_summary', 'Summary of weather conditions'),
        new StringSchema('recommendation', 'Recommendation on what to wear'),
    ],
    requiredFields: ['game_time', 'weather_summary', 'recommendation']
);

$tools = [
    Tool::as('get_weather')
        ->for('Get current weather for a location')
        ->withStringParameter('city', 'The city name')
        ->using(fn (string $city): string =>
            "Weather in {$city}: 45°F and cold"
        ),
    Tool::as('search_games')
        ->for('Search for game times in a city')
        ->withStringParameter('city', 'The city name')
        ->using(fn (string $city): string =>
            'The Tigers game is at 3pm in Detroit'
        ),
];

$response = Prism::structured()
    ->using('openai', 'gpt-4o')
    ->withSchema($schema)
    ->withTools($tools)
    ->withMaxSteps(5)
    ->withPrompt('What time is the Tigers game today in Detroit and should I wear a coat?')
    ->asStructured();
```

--------------------------------

### Model Selection Guide

Source: https://github.com/prism-php/prism/blob/main/docs/providers/groq.md

Choose the appropriate Whisper model for your transcription needs.

```APIDOC
## [POST] /audio/stt/model-selection

### Description
Transcribes audio using different Whisper models based on speed and language requirements.

### Method
POST

### Endpoint
/audio/stt/model-selection

### Parameters
#### Request Body
- **model** (string) - Required - The model identifier: 'whisper-large-v3', 'distil-whisper-large-v3-en', or 'whisper-large-v3-turbo'.
- **input** (audio) - Required - The audio file to transcribe.

### Request Example
```php
$response = Prism::audio()
    ->using('groq', 'whisper-large-v3')
    ->withInput($audioFile)
    ->asText();

// For fastest English-only transcription
$response = Prism::audio()
    ->using('groq', 'distil-whisper-large-v3-en')
    ->withInput($audioFile)
    ->asText();

// For balanced speed and multilingual capability
$response = Prism::audio()
    ->using('groq', 'whisper-large-v3-turbo')
    ->withInput($audioFile)
    ->asText();
```

### Response
#### Success Response (200)
- **text** (string) - The transcribed text.

#### Response Example
```php
$response = Prism::audio()
    ->using('groq', 'whisper-large-v3')
    ->withInput($audioFile)
    ->asText();
```
```

--------------------------------

### Response Formats - verbose_json

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/audio.md

Use verbose_json response format to get timestamps and confidence scores.

```APIDOC
## Response Formats - verbose_json

### Description
Use verbose_json response format to get timestamps and confidence scores.

### Method
withProviderOptions

### Parameters
- **options** (array) - Required - Provider-specific options.
  - **response_format** (string) - Optional - Set to 'verbose_json' for detailed output.

### Request Example
```php
$response = Prism::audio()
    ->using('openai', 'whisper-1')
    ->withInput($audioFile)
    ->withProviderOptions([
        'response_format' => 'verbose_json',
    ])
    ->asText();
```

### Response
Returns a text response object with additional metadata in `additionalContent`.

### Response Example
```php
$metadata = $response->additionalContent;
if (isset($metadata['segments'])) {
    foreach ($metadata['segments'] as $segment) {
        echo "Segment: " . $segment['text'] . "\n";
        echo "Start: " . $segment['start'] . "s\n";
        echo "End: " . $segment['end'] . "s\n";
    }
}
```
```

--------------------------------

### Create a basic search tool with Tool::as

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/tools-function-calling.md

Defines a tool named 'search' with a string parameter 'query' and a closure that returns a string. The tool must always return a string.

```php
use Prism\Prism\Facades\Tool;

$searchTool = Tool::as('search')
    ->for('Search for current information')
    ->withStringParameter('query', 'The search query')
    ->using(function (string $query): string {
        // Your search implementation
        return "Search results for: {$query}";
    });
```

--------------------------------

### Response Formats

Source: https://github.com/prism-php/prism/blob/main/docs/providers/groq.md

Get transcriptions in different formats including JSON, text, and verbose JSON with timestamps.

```APIDOC
## [POST] /audio/stt/response-formats

### Description
Transcribes audio with configurable response format and timestamp granularity.

### Method
POST

### Endpoint
/audio/stt/response-formats

### Parameters
#### Request Body
- **model** (string) - Required - The model identifier, e.g., 'whisper-large-v3'.
- **input** (audio) - Required - The audio file to transcribe.
- **response_format** (string) - Optional - Format: 'json', 'text', or 'verbose_json'.
- **timestamp_granularities** (array) - Optional - Granularity: 'word' or 'segment'.

### Request Example
```php
// Standard JSON response
$response = Prism::audio()
    ->using('groq', 'whisper-large-v3')
    ->withInput($audioFile)
    ->withProviderOptions([
        'response_format' => 'json',  // json, text, verbose_json
    ])
    ->asText();

// Verbose JSON includes timestamps and segments
$response = Prism::audio()
    ->using('groq', 'whisper-large-v3')
    ->withInput($audioFile)
    ->withProviderOptions([
        'response_format' => 'verbose_json',
        'timestamp_granularities' => ['segment'], // word, segment
    ])
    ->asText();

// Access detailed segment information
$segments = $response->additionalContent['segments'] ?? [];
foreach ($segments as $segment) {
    echo "Text: " . $segment['text'] . "\n";
    echo "Start: " . $segment['start'] . "s\n";
    echo "End: " . $segment['end'] . "s\n";
}
```

### Response
#### Success Response (200)
- **text** (string) - The transcribed text.
- **additionalContent** (object) - Contains segments array with text, start, and end timestamps when verbose_json is used.

#### Response Example
```php
$segments = $response->additionalContent['segments'] ?? [];
foreach ($segments as $segment) {
    echo "Text: " . $segment['text'] . "\n";
    echo "Start: " . $segment['start'] . "s\n";
    echo "End: " . $segment['end'] . "s\n";
}
```
```

--------------------------------

### Using withMessages to include a video

Source: https://github.com/prism-php/prism/blob/main/docs/input-modalities/video.md

Creates a UserMessage with a video from a local file path and sends it to Gemini using the withMessages method.

```php
use Prism\Prism\ValueObjects\Messages\UserMessage;
use Prism\Prism\ValueObjects\Media\Video;

$message = new UserMessage(
    "What's in this video?",
    [Video::fromLocalPath(path: '/path/to/video.mp4')]
);

$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withMessages([$message])
    ->asText();
```

--------------------------------

### Customize image filenames with as() method

Source: https://github.com/prism-php/prism/blob/main/docs/input-modalities/images.md

Demonstrates using the fluent as() method to provide custom filenames for images when uploading. This is useful for readability and debugging when working with multiple images. Uses the openai provider with the gpt-image-1 model.

```php
use Prism\Prism\ValueObjects\Media\Image;

$response = Prism::image()
    ->using('openai', 'gpt-image-1')
    ->withPrompt('Edit these images', [
        Image::fromLocalPath('path/to/photo1.png')->as('original-photo.png'),
        Image::fromLocalPath('path/to/photo2.png')->as('reference-image.png'),
    ])
    ->generate();
```

--------------------------------

### Create a BooleanSchema for true/false values

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/schemas.md

Use BooleanSchema to define a boolean field. The example creates a schema for an active flag.

```php
use Prism\Prism\Schema\BooleanSchema;

$activeSchema = new BooleanSchema(
    name: 'is_active',
    description: 'Whether the user account is active'
);
```

--------------------------------

### Configure Imagen options with Prism::image()

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/image-generation.md

Shows how to pass provider options for Gemini's Imagen model, including number of images, size, aspect ratio, and person generation. The 'size' option defaults to '1K' and 'aspect_ratio' defaults to '1:1'.

```php
$response = Prism::image()
    ->using(Provider::Gemini, 'imagen-4.0-generate-001')
    ->withPrompt('Generate an image of a magnificent building falling into the ocean')
    ->withProviderOptions([
        'n' => 3,                               // number of images to generate
        'size' => '2K',                         // 1K (default), 2K
        'aspect_ratio' => '16:9',               // 1:1 (default), 3:4, 4:3, 9:16, 16:9
        'person_generation' => 'dont_allow',    // dont_allow, allow_adult, allow_all
    ])
    ->generate();
```

--------------------------------

### Enable Google search grounding with withProviderTools

Source: https://github.com/prism-php/prism/blob/main/docs/providers/gemini.md

Example of enabling Google search grounding on a text request using the withProviderTools method with a ProviderTool for 'google_search'. Requires the Gemini provider and a model like 'gemini-2.0-flash'.

```php
use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;
use Prism\Prism\ValueObjects\ProviderTool;

$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-2.0-flash')
    ->withPrompt('What is the stock price of Google right now?')
    // Enable search grounding
    ->withProviderTools([
            new ProviderTool('google_search')
        ])
    ->asText();
```

--------------------------------

### List available models curl request

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/prism-server.md

Sends a GET request to the models endpoint to retrieve a list of all registered Prism models.

```bash
curl "http://your-app.com/prism/openai/v1/models"
```

--------------------------------

### Creating Audio Objects for Groq STT

Source: https://github.com/prism-php/prism/blob/main/docs/providers/groq.md

Shows four ways to create Audio objects: from a local file path, from a remote URL (recommended for large files), from base64 data, and from binary content. Each method requires the appropriate MIME type.

```php
use Prism\Prism\ValueObjects\Media\Audio;

// From local file path
$audio = Audio::fromPath('/path/to/audio.mp3');

// From remote URL (recommended for large files)
$audio = Audio::fromUrl('https://example.com/recording.wav');

// From base64 encoded data
$audio = Audio::fromBase64($base64AudioData, 'audio/mpeg');

// From binary content
$audioContent = file_get_contents('/path/to/audio.wav');
$audio = Audio::fromContent($audioContent, 'audio/wav');
```

--------------------------------

### Combine tools with structured output using Gemini

Source: https://github.com/prism-php/prism/blob/main/docs/providers/gemini.md

Shows how to define a structured output schema, create a tool, and call Prism::structured() with the Gemini provider. The AI can call the tool to gather data and return a structured response. Note: set `maxSteps` to at least 2 when combining tools with structured output.

```php
use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;
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('gemini', 'gemini-2.0-flash')
    ->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);

// Access tool execution details
foreach ($response->toolCalls as $toolCall) {
    echo "Called: {$toolCall->name}\n";
}
```

--------------------------------

### Message chain with withMessages()

Source: https://github.com/prism-php/prism/blob/main/tests/Fixtures/test-embedding-file.md

Maintains conversation context by passing an array of UserMessage and AssistantMessage objects to withMessages(). The example shows a three-message exchange.

```php
use Prism\Prism\ValueObjects\Messages\UserMessage;
use Prism\Prism\ValueObjects\Messages\AssistantMessage;

$response = Prism::text()
    ->using(Provider::Anthropic, 'claude-3-sonnet')
    ->withMessages([
        new UserMessage('What is JSON?'),
        new AssistantMessage('JSON is a lightweight data format...'),
        new UserMessage('Can you show me an example?')
    ])
    ->generate();
```

--------------------------------

### Transcribing Audio with Gemini

Source: https://github.com/prism-php/prism/blob/main/docs/providers/gemini.md

Use the Audio value object to pass a local audio file for transcription or analysis. The example uses gemini-1.5-flash.

```php
use Prism\Prism\ValueObjects\Messages\UserMessage;
use Prism\Prism\ValueObjects\Media\Audio;
use Prism\Prism\Enums\Provider;

$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withMessages([
        new UserMessage(
            'Transcribe this audio file:',
            additionalContent: [
                Audio::fromLocalPath('/path/to/audio.mp3'),
            ],
        ),
    ])
    ->asText();
```

--------------------------------

### Summarizing YouTube Video with Gemini

Source: https://github.com/prism-php/prism/blob/main/docs/providers/gemini.md

Pass a YouTube URL to the Video value object to analyze or summarize the content. The example uses gemini-1.5-flash.

```php
use Prism\Prism\ValueObjects\Messages\UserMessage;
use Prism\Prism\ValueObjects\Media\Video;
use Prism\Prism\Enums\Provider;

$response = Prism::text()
    ->using(Provider::Gemini, 'gemini-1.5-flash')
    ->withMessages([
        new UserMessage(
            'Summarize this YouTube video:',
            additionalContent: [
                Video::fromUrl('https://www.youtube.com/watch?v=dQw4w9WgXcQ'),
            ],
        ),
    ])
    ->asText();
```

--------------------------------

### Add documents to a prompt using withPrompt and Document

Source: https://github.com/prism-php/prism/blob/main/docs/input-modalities/documents.md

Shows how to use Prism::text()->withPrompt() with a Document value object to include a document in a prompt. The example covers all supported creation methods: fromLocalPath, fromStoragePath, fromBase64, fromRawContent, fromText, fromUrl, fromChunks, and fromFileId. Optional parameters like title, mimeType, and diskName are marked with comments.

```php
use Prism\Prism\Enums\Provider;
use Prism\Prism\Facades\Prism;
use Prism\Prism\ValueObjects\Media\Document;

// From a local path
$response = Prism::text()
    ->using('my-provider', 'my-model')
    ->withPrompt(
        'Analyze this document',
        [Document::fromLocalPath(
            path: 'tests/Fixtures/test-pdf.pdf',
            title: 'My document title' // optional
        )]
    )
    ->asText();

// From a storage path
$response = Prism::text()
    ->using('my-provider', 'my-model')
    ->withPrompt(
        'Summarize this document',
        [Document::fromStoragePath(
            path: 'mystoragepath/file.pdf',
            diskName: 'my-disk', // optional - omit/null for default disk
            title: 'My document title' // optional
        )]
    )
    ->asText();

// From base64
$response = Prism::text()
    ->using('my-provider', 'my-model')
    ->withPrompt(
        'Extract key points from this document',
        [Document::fromBase64(
            base64: $baseFromDB,
            mimeType: 'optional/mimetype', // optional
            title: 'My document title' // optional
        )]
    )
    ->asText();

// From raw content
$response = Prism::text()
    ->using('my-provider', 'my-model')
    ->withPrompt(
        'Review this document',
        [Document::fromRawContent(
            rawContent: $rawContent,
            mimeType: 'optional/mimetype', // optional
            title: 'My document title' // optional
        )]
    )
    ->asText();

// From a text string
$response = Prism::text()
    ->using('my-provider', 'my-model')
    ->withPrompt(
        'Process this text document',
        [Document::fromText(
            text: 'Hello world!',
            title: 'My document title' // optional
        )]
    )
    ->asText();

// From an URL
$response = Prism::text()
    ->using('my-provider', 'my-model')
    ->withPrompt(
        'Analyze this document from URL',
        [Document::fromUrl(
            url: 'https://example.com/test-pdf.pdf',
            title: 'My document title' // optional
        )]
    )
    ->asText();

// From chunks
$response = Prism::text()
    ->using('my-provider', 'my-model')
    ->withPrompt(
        'Process this chunked document',
        [Document::fromChunks(
            chunks: [
                'chunk one',
                'chunk two'
            ],
            title: 'My document title' // optional
        )]
    )
    ->asText();

// From a provider file ID
$response = Prism::text()
    ->using('my-provider', 'my-model')
    ->withPrompt(
        'Analyze this document from provider file',
        [Document::fromFileId(
            fileId: 'my-provider-file-id'
        )]
    )
    ->asText();
```

--------------------------------

### Enable Citations with withProviderOptions

Source: https://github.com/prism-php/prism/blob/main/docs/providers/anthropic.md

Enable citations by passing ['citations' => true] to withProviderOptions(). Note that citations cannot be used with native structured output mode; use tool calling mode via withProviderOptions(['use_tool_calling' => true, 'citations' => true]) if needed.

```php
use Prism\Prism\Enums\Provider;
use Prism\Prism\Facades\Prism;
use Prism\Prism\ValueObjects\Messages\UserMessage;
use Prism\Prism\ValueObjects\Media\Document;

$response = Prism::text()
    ->using(Provider::Anthropic, 'claude-3-5-sonnet-20241022')
    ->withMessages([
        new UserMessage(
            content: "Is the grass green and the sky blue?",
            additionalContent: [
                Document::fromChunks(
                    chunks: ["The grass is green.", "Flamingos are pink.", "The sky is blue."],
                    title: 'The colours of nature',
                    context: 'The go-to textbook on the colours found in nature!'
                )
            ]
        )
    ])
    ->withProviderOptions(['citations' => true])
    ->asText();

```

--------------------------------

### Create a NumberSchema for numeric values

Source: https://github.com/prism-php/prism/blob/main/docs/core-concepts/schemas.md

Use NumberSchema to define a numeric field. The example creates a schema for a user's age in years.

```php
use Prism\Prism\Schema\NumberSchema;

$ageSchema = new NumberSchema(
    name: 'age',
    description: 'The user\'s age in years'
);
```
Tokens:
Raw