PHP Prisma

// Resolves to \Aimeos\Prisma\Providers\Text\Myprovider
$provider = Prisma::text()->using( 'myprovider', ['api_key' => '...'] );

// Resolves to \Aimeos\Prisma\Providers\Image\Myprovider
$provider = Prisma::image()->using( 'myprovider', ['api_key' => '...'] );

if( Prisma::supports( 'text', 'myprovider', 'write', $config ) ) {
    // provider has a write() method
}

Prisma::fake( [TextResponse::fromText( 'Hello' )] );

namespace Aimeos\Prisma\Contracts\Embedding;

use Aimeos\Prisma\Responses\VectorResponse;

interface Embed
{
    public function embed( array $texts, ?int $size = null, array $options = [] ) : VectorResponse;
}

namespace Aimeos\Prisma\Providers\Embedding;

use Aimeos\Prisma\Contracts\Embedding\Embed;
use Aimeos\Prisma\Exceptions\PrismaException;
use Aimeos\Prisma\Providers\Base;
use Aimeos\Prisma\Responses\VectorResponse;

class Openai extends Base implements Embed
{
    public function __construct( array $config )
    {
        if( !isset( $config['api_key'] ) ) {
            throw new PrismaException( 'No API key' );
        }

        $this->header( 'Authorization', 'Bearer ' . $config['api_key'] );
        $this->baseUrl( 'https://api.openai.com' );
    }

    public function embed( array $texts, ?int $size = null, array $options = [] ) : VectorResponse
    {
        $options = $this->allowed( $options, ['model'] );

        $response = $this->client()->post( 'v1/embeddings', ['json' => [
            'model' => $options['model'] ?? 'text-embedding-3-small',
            'input' => $texts,
            'dimensions' => $size,
        ]] );

        $this->validate( $response );
        $data = $this->fromJson( $response );

        $vectors = array_map( fn( $item ) => $item['embedding'], $data['data'] ?? [] );

        return VectorResponse::fromVectors( $vectors )
            ->withUsage( $data['usage']['total_tokens'] ?? null, $data['usage'] ?? [] );
    }
}

use Aimeos\Prisma\Prisma;

$provider = Prisma::type( 'embedding' )->using( 'openai', ['api_key' => '...'] );
$response = $provider->embed( ['Hello world', 'Another text'], 256 );

<?php

// for Audio providers
namespace Aimeos\Prisma\Providers\Audio;
// for Image providers
namespace Aimeos\Prisma\Providers\Image;
// for Text providers
namespace Aimeos\Prisma\Providers\Text;
// for Video providers
namespace Aimeos\Prisma\Providers\Video;

use Aimeos\Prisma\Exceptions\PrismaException;
use Aimeos\Prisma\Providers\Base;


class Myprovider extends Base implements ...
{
    public function __construct( array $config )
    {
        if( !isset( $config['api_key'] ) ) {
            throw new PrismaException( sprintf( 'No API key' ) );
        }

        // if authentication is done via headers
        $this->header( '<api key name>', $config['api_key'] );
        // base url for all requests (no paths)
        $this->baseUrl( '<provider URL>' );
    }

namespace Aimeos\Prisma\Providers\Image;

use Aimeos\Prisma\Contracts\Image\Describe;
use Aimeos\Prisma\Exceptions\PrismaException;
use Aimeos\Prisma\Files\Image;
use Aimeos\Prisma\Providers\Base;
use Aimeos\Prisma\Responses\TextResponse;


class Myprovider extends Base implements Describe
{
    public function describe( Image $image, ?string $lang = null, array $options = [] ) : TextResponse
    {
        // ...
    }
}

protected function cfg( array $config, string $key, string $default = '' ) : string

public function __construct( array $config )
{
    if( !isset( $config['api_key'] ) ) {
        throw new PrismaException( 'No API key' );
    }

    $this->header( 'Authorization', 'Bearer ' . $this->cfg( $config, 'api_key' ) );
    $this->baseUrl( $this->cfg( $config, 'url', 'https://api.default.com' ) );
}

$payload = [
    'model' => $this->modelName( 'default-model' ),
    'messages' => [['role' => 'user', 'content' => $prompt]],
];

if( $system = $this->systemPrompt() ) {
    $payload['system'] = $system;
}

$payload['max_tokens'] = $this->maxTokens() ?? 4096;

if( $budget = $this->thinkingBudget() ) {
    $payload['thinking'] = ['type' => 'enabled', 'budget_tokens' => $budget];
}

use Aimeos\Prisma\Files\Image;

$file = Image::fromBinary( $binaryData, 'image/png' );
$file = Image::fromBase64( $base64Data, 'image/png' );
$file = Image::fromUrl( 'https://example.com/photo.jpg', 'image/jpeg' );
$file = Image::fromLocalPath( '/path/to/photo.jpg' );
$file = Image::fromStoragePath( 'photos/image.jpg', 'public', 'image/jpeg' );

$file->binary();    // raw binary content (fetches from URL if needed)
$file->base64();    // base64-encoded content
$file->url();       // original URL (if created from URL)
$file->mimeType();  // mime type string
$file->filename();  // filename (if available)
$file->as( 'name.png' );  // set the filename

// filter key/value pairs in $options and use the ones allowed by the API
$allowed = $this->allowed( $options, ['<key1>', '<key2>', /* ... */] );

// filter values to pass only allowed option values (optional)
$allowed = $this->sanitize( $allowed, ['<key1>' => ['<val1>', '<val2>', '<val3>']])

$model = $this->modelName( 'gemini-2.5-flash' );

// Form data request
$data = $this->request( $params );
// Multipart request
$data = ['multipart' => $this->request( $params, ['image_key' => $image->binary()] )];
// JSON request
$data = ['json' => ['image_key' => array_map( fn( $image ) => $image->base64(), $images )] + $params];

$response = $this->client()->post( 'relative/api/path', $data );
$this->validate( $response );
$content = $response->getBody()->getContents();

use Aimeos\Prisma\Files\Image;
use Aimeos\Prisma\Responses\TextResponse;

public function describe( Image $image, ?string $lang = null, array $options = [] ) : TextResponse
{
    $model = $this->modelName( 'flash' );
    $allowed = $this->allowed( $options, ['version'] );

    $params = ['language' => $lang] + $allowed;
    $data = ['multipart' => $this->request( $params, ['file' => $image->binary()] )];
    $response = $this->client()->post( 'relative/api/path', $data );

    $this->validate( $response );

    $content = $response->getBody()->getContents();
    // return a response
}

$data = $this->fromJson( $response );

use Psr\Http\Message\ResponseInterface;

protected function validate( ResponseInterface $response ) : void
{
    if( $response->getStatusCode() === 200 ) {
        return;
    }

    $data = $this->fromJson( $response );
    $error = $data['detail'] ?? $response->getReasonPhrase();

    // remap status codes if needed (e.g. API returns 422 for auth errors)
    $this->throw( match( $response->getStatusCode() ) {
        422 => 400,
        default => $response->getStatusCode(),
    }, is_string( $error ) ? $error : '' );
}

use Aimeos\Prisma\Responses\FileResponse;

$response = FileResponse::fromBinary( '...', 'image/png' );
$response = FileResponse::fromBase64( '...', 'image/png' );
$response = FileResponse::fromUrl( '...', 'image/png' );

use Aimeos\Prisma\Files\File;

$response->add( File::fromBinary( '...', 'image/png' ) );

use Aimeos\Prisma\Responses\TextResponse;

$response = TextResponse::fromText( '...' );
$response->add( '...' ); // add more texts

use Aimeos\Prisma\Responses\VectorResponse;

$response = VectorResponse::fromVectors( [
    [0.27629, 0.89271, 0.98265, /* ... */],
    /* ... */
] );

$response->withUsage( // optional
    100, // used tokens, credits, etc. if available or NULL
    [] // arbitrary key/value pairs for the rest of the usage information
);
$response->withMeta( // optional
    [] // arbitrary meta data as key/value pairs, can be nested
);

$response->withStructured( [
    // for transcriptions
    ['start' => 0.0, 'end' => 1.0, 'text' => 'This is a test.'],
    // ...
] );

$response->withDescription( '...' );

return TextResponse::fromText( $data['text'] ?? '' )
    ->withReason( match( $data['finish_reason'] ?? '' ) {
        'stop' => self::STOP,
        'length' => self::LENGTH,
        'tool_calls' => self::TOOL,
        'content_filter' => self::CONTENT,
        default => self::UNKNOWN,
    } );

use Aimeos\Prisma\Values\Citation;

$citations = [];

foreach( $data['citations'] ?? [] as $cit ) {
    $citations[] = new Citation(
        title: $cit['title'] ?? null,
        url: $cit['url'] ?? null,
        text: $cit['cited_text'] ?? null,
        source: $cit['source_text'] ?? null,
    );
}

return TextResponse::fromText( $data['text'] ?? '' )
    ->withCitations( $citations );

use Aimeos\Prisma\Tools\Step;

// after executing tools with execTools()
return TextResponse::fromText( $data['text'] ?? '' )
    ->withSteps( $allSteps );

$response = $this->client()->post( 'v1/chat', $data );
$this->validate( $response );
$data = $this->fromJson( $response );

return TextResponse::fromText( $data['text'] ?? '' )
    ->withRateLimit( $this->getRateLimit( $response ) );

$rateLimit = $response->rateLimit();
$rateLimit->limit();       // request limit (int or null)
$rateLimit->remaining();   // remaining requests (int or null)
$rateLimit->reset();       // reset timestamp (string or null)
$rateLimit->retryAfter();  // retry after seconds (int or null)

use Aimeos\Prisma\Schema\Schema;

$schema = Schema::for( 'person', [
    'name' => Schema::string()->description( 'Full name' )->required(),
    'age' => Schema::integer()->description( 'Age in years' ),
    'tags' => Schema::array()->items( Schema::string() ),
    'address' => Schema::object( [
        'city' => Schema::string()->required(),
        'zip' => Schema::string(),
    ] ),
] );

$schema = Schema::fromArray( 'person', $jsonSchemaArray );

Schema::string()->enum( ['draft', 'published', 'archived'] )
Schema::string()->enum( StatusEnum::class )

$schema->toArray();    // full JSON Schema array
$schema->toString();   // JSON string
$schema->filter( ['type', 'description', 'properties', 'required', 'items'] );  // filtered schema
$schema->name();       // schema name
$schema->strict();     // enable strict mode
$schema->isStrict();   // check strict mode

use Aimeos\Prisma\Schema\Schema;
use Aimeos\Prisma\Responses\TextResponse;

public function structure( string $prompt, Schema $schema, array $files = [], array $options = [] ) : TextResponse
{
    $allowed = $this->allowed( $options, ['temperature'] );
    $model = $this->modelName( 'default-model' );

    $payload = [
        'model' => $model,
        'messages' => [['role' => 'user', 'content' => $prompt]],
        'response_format' => [
            'type' => 'json_schema',
            'json_schema' => [
                'name' => $schema->name(),
                'schema' => $schema->toArray(),
                'strict' => $schema->isStrict(),
            ],
        ],
    ] + $allowed;

    $response = $this->client()->post( 'v1/chat/completions', ['json' => $payload] );
    $this->validate( $response );
    $data = $this->fromJson( $response );

    $text = $data['choices'][0]['message']['content'] ?? '';
    $structured = json_decode( $text, true ) ?: [];

    return TextResponse::fromText( $text )->withStructured( $structured );
}

$schemaPrompt = $prompt
    . "\n\nRespond with ONLY valid JSON matching this schema:\n"
    . $schema->toString();

// ... send $schemaPrompt to the API ...

$text = trim( $data['text'] ?? '' );
$text = preg_replace( '/^```(?:json)?\s*|\s*```$/s', '', $text ) ?? $text;
$structured = json_decode( $text, true ) ?: [];

return TextResponse::fromText( $text )->withStructured( $structured );

// Format tools array for the API
protected function toolsParam() : array
{
    $tools = [];

    foreach( $this->tools() as $tool ) {
        $tools[] = [
            'name' => $tool->name(),
            'description' => $tool->description(),
            'parameters' => $tool->schema()->toArray(),
        ];
    }

    return $tools;
}


// Extract tool calls from API response
protected function parseToolCalls( array $result ) : array
{
    $toolCalls = [];

    foreach( $result['tool_calls'] ?? [] as $call ) {
        $toolCalls[] = [
            'id' => $call['id'] ?? null,
            'name' => $call['function']['name'] ?? '',
            'arguments' => json_decode( $call['function']['arguments'] ?? '{}', true ) ?: [],
        ];
    }

    return $toolCalls;
}


// Format tool results as messages for the next API call
protected function toolResults( array $results ) : array
{
    $messages = [];

    foreach( $results as $step ) {
        $messages[] = [
            'role' => 'tool',
            'tool_call_id' => $step->id(),
            'content' => $step->result(),
        ];
    }

    return $messages;
}

private function generate( array $messages, array $options ) : TextResponse
{
    $allSteps = [];

    for( $step = 1; $step <= $this->maxSteps(); $step++ )
    {
        $params = [
            'model' => $this->modelName( 'default-model' ),
            'messages' => $messages,
        ] + $options;

        if( $tools = $this->toolsParam() ) {
            $params['tools'] = $tools;
            $params['tool_choice'] = $this->toolChoice();
        }

        $response = $this->client()->post( 'v1/chat/completions', ['json' => $params] );
        $this->validate( $response );
        $result = $this->fromJson( $response );

        $toolCalls = $this->parseToolCalls( $result );

        if( !$toolCalls ) {
            break;
        }

        $toolResults = $this->execTools( $toolCalls );
        array_push( $allSteps, ...$toolResults );

        $messages[] = $result['choices'][0]['message'] ?? [];
        $messages = array_merge( $messages, $this->toolResults( $toolResults ) );
    }

    $text = $result['choices'][0]['message']['content'] ?? '';

    return TextResponse::fromText( $text )
        ->withSteps( $allSteps )
        ->withReason( $toolCalls ? self::TOOL : self::STOP );
}

private static array $providerToolMap = [
    'web_search' => [
        'type' => 'web_search',
        'options' => ['allowed_domains', 'search_context_size'],
    ],
    'code_execution' => [
        'type' => 'code_interpreter',
    ],
];


protected function toolsParam() : array
{
    $tools = [];

    foreach( $this->tools() as $tool ) {
        $tools[] = [
            'name' => $tool->name(),
            'description' => $tool->description(),
            'parameters' => $tool->schema()->toArray(),
        ];
    }

    return array_merge( $tools, $this->mapProviderTools( self::$providerToolMap ) );
}

FileResponse::fromAsync( Closure $closure, int $retry = 5 ) : FileResponse
TextResponse::fromAsync( Closure $closure, int $retry = 5 ) : TextResponse

use Aimeos\Prisma\Files\Image;
use Aimeos\Prisma\Responses\FileResponse;

public function imagine( string $prompt, array $images = [], array $options = [] ) : FileResponse
{
    $response = $this->client()->post( 'v1/generate', ['json' => ['prompt' => $prompt]] );
    $this->validate( $response );
    $data = $this->fromJson( $response );

    return FileResponse::fromAsync( $this->download( $data['polling_url'] ?? '' ), 2 );
}


protected function download( string $url ) : \Closure
{
    $client = $this->client();

    return function( FileResponse $fr ) use ( $client, $url ) : bool {
        $response = $client->get( $url );
        $data = json_decode( $response->getBody()->getContents(), true ) ?: [];

        if( ( $data['status'] ?? '' ) !== 'Ready' ) {
            return false;
        }

        $fr->add( Image::fromUrl( $data['url'] ?? '' ) );
        return true;
    };
}

use Aimeos\Prisma\Responses\TextResponse;

return TextResponse::fromAsync( function( TextResponse $tr ) use ( $client, $id ) : bool {
    $response = $client->get( "v1/jobs/{$id}" );
    $data = json_decode( $response->getBody()->getContents(), true ) ?: [];

    if( ( $data['status'] ?? '' ) !== 'COMPLETED' ) {
        return false;
    }

    $tr->add( $data['text'] ?? '' );
    return true;
}, 3 );

<?php

namespace Aimeos\Prisma\Providers;

use Aimeos\Prisma\Concerns\CallsTools;
use Aimeos\Prisma\Concerns\OpenaiApi;
use Aimeos\Prisma\Exceptions\PrismaException;


class Myprovider extends Base
{
    use CallsTools;
    use OpenaiApi;

    public function __construct( array $config )
    {
        if( !isset( $config['api_key'] ) ) {
            throw new PrismaException( 'No API key' );
        }

        $this->header( 'Authorization', 'Bearer ' . $this->cfg( $config, 'api_key' ) );
        $this->baseUrl( $this->cfg( $config, 'url', 'https://api.myprovider.com' ) );
    }
}

<?php

namespace Aimeos\Prisma\Providers\Text;

use Aimeos\Prisma\Contracts\Text\Structure;
use Aimeos\Prisma\Contracts\Text\Write;
use Aimeos\Prisma\Providers\Myprovider as Base;
use Aimeos\Prisma\Responses\TextResponse;
use Aimeos\Prisma\Schema\Schema;


class Myprovider extends Base implements Structure, Write
{
    public function structure( string $prompt, Schema $schema, array $files = [], array $options = [] ) : TextResponse
    {
        $options = $this->allowed( $options, ['temperature', 'top_p'] );

        return $this->structuredCompletions(
            'v1/chat/completions', 'default-model',
            $this->messages( $this->content( $prompt, $files ) ),
            $schema, $options
        );
    }


    public function write( string $prompt, array $files = [], array $options = [] ) : TextResponse
    {
        $options = $this->allowed( $options, ['temperature', 'top_p'] );

        return $this->completions(
            'v1/chat/completions', 'default-model',
            $this->messages( $this->content( $prompt, $files ) ),
            $options
        );
    }
}

<?php

namespace Aimeos\Prisma\Providers;

use Aimeos\Prisma\Exceptions\PrismaException;


class Myprovider extends Base
{
    public function __construct( array $config )
    {
        if( !isset( $config['api_key'] ) ) {
            throw new PrismaException( 'No API key' );
        }

        $this->header( 'Authorization', 'Bearer ' . $this->cfg( $config, 'api_key' ) );
        $this->baseUrl( $this->cfg( $config, 'url', 'https://api.myprovider.com' ) );
    }


    protected function content( string $prompt, array $files ) : array
    {
        // shared logic for building content blocks from prompt and files
        $parts = [['type' => 'text', 'text' => $prompt]];

        foreach( $files as $file ) {
            $parts[] = ['type' => 'image', 'data' => $file->base64()];
        }

        return $parts;
    }
}

<?php

namespace Aimeos\Prisma\Providers\Text;

use Aimeos\Prisma\Contracts\Text\Write;
use Aimeos\Prisma\Providers\Myprovider as Base;
use Aimeos\Prisma\Responses\TextResponse;


class Myprovider extends Base implements Write
{
    public function write( string $prompt, array $files = [], array $options = [] ) : TextResponse
    {
        $allowed = $this->allowed( $options, ['temperature', 'top_p'] );

        $payload = [
            'model' => $this->modelName( 'default-model' ),
            'messages' => [['role' => 'user', 'content' => $this->content( $prompt, $files )]],
        ] + $allowed;

        if( $system = $this->systemPrompt() ) {
            $payload['system'] = $system;
        }

        $response = $this->client()->post( 'v1/chat', ['json' => $payload] );
        $this->validate( $response );
        $data = $this->fromJson( $response );

        return TextResponse::fromText( $data['choices'][0]['message']['content'] ?? '' )
            ->withUsage( $data['usage']['total_tokens'] ?? null, $data['usage'] ?? [] )
            ->withRateLimit( $this->getRateLimit( $response ) );
    }
}

<?php

namespace Aimeos\Prisma\Providers\Image; // or Audio, Video

use Aimeos\Prisma\Contracts\Image\Describe; // or Audio\Describe, Video\Describe
use Aimeos\Prisma\Exceptions\PrismaException;
use Aimeos\Prisma\Files\Image; // or Audio, Video
use Aimeos\Prisma\Providers\Base;
use Aimeos\Prisma\Responses\TextResponse;


class Myprovider extends Base implements Describe
{
    public function __construct( array $config )
    {
        if( !isset( $config['api_key'] ) ) {
            throw new PrismaException( 'No API key' );
        }

        $this->header( 'x-api-key', $config['api_key'] );
        $this->baseUrl( 'https://ai.com' );
    }


    public function describe( Image $image, ?string $lang = null, array $options = [] ) : TextResponse
    {
        $allowed = $this->allowed( $options, ['version'] );
        $model = $this->modelName( 'flash' );

        $params = ['language' => $lang, 'model' => $model] + $allowed;
        $data = ['multipart' => $this->request( $params, ['file' => $image->binary()] )];
        $response = $this->client()->post( 'relative/api/path', $data );

        $this->validate( $response );

        $data = $this->fromJson( $response );

        return TextResponse::fromText( $data['text'] ?? '' )
            ->withStructured( $data['segments'] ?? [] )
            ->withUsage( $data['usage']['total'] ?? null, $data['usage'] ?? [] )
            ->withMeta( $data['meta'] ?? [] );
    }
}

<?php

namespace Aimeos\Prisma\Providers\Text;

use Aimeos\Prisma\Contracts\Text\Translate;
use Aimeos\Prisma\Exceptions\PrismaException;
use Aimeos\Prisma\Providers\Base;
use Aimeos\Prisma\Responses\TextResponse;


class Myprovider extends Base implements Translate
{
    public function __construct( array $config )
    {
        if( !isset( $config['api_key'] ) ) {
            throw new PrismaException( 'No API key' );
        }

        $this->header( 'Authorization', 'Bearer ' . $config['api_key'] );
        $this->baseUrl( 'https://ai.com' );
    }


    public function translate( array $texts, string $to, ?string $from = null, ?string $context = null, array $options = [] ) : TextResponse
    {
        $payload = [
            'texts' => $texts,
            'target_lang' => $to,
            'source_lang' => $from,
        ] + $this->allowed( $options, ['formality'] );

        $response = $this->client()->post( '/v1/translate', ['json' => $payload] );
        $this->validate( $response );

        $data = $this->fromJson( $response );
        $translated = array_map( fn( $item ) => $item['text'] ?? '', $data ?? [] );

        return TextResponse::fromTexts( $translated )
            ->withUsage( $data['usage']['total'] ?? 0, $data['usage'] ?? [] )
            ->withMeta( $data['meta'] ?? [] );
    }
}

use Tests\MakesPrismaRequests;
use PHPUnit\Framework\TestCase;

class MyproviderTest extends TestCase
{
    use MakesPrismaRequests;

    public function testDescribe() : void
    {
        $this->prisma( 'image', 'myprovider', ['api_key' => 'test'] );

        $result = $this->response( ['text' => 'A photo of a cat'] )
            ->describe( Image::fromUrl( 'https://example.com/cat.jpg' ) );

        $this->assertEquals( 'A photo of a cat', $result->text() );

        $this->assertPrismaRequest( function( $request, $options ) {
            return str_contains( $request->getUri()->getPath(), 'relative/api/path' );
        } );
    }
}

$this->prisma( 'text', 'myprovider', ['api_key' => 'test'] );

$this->response( ['status' => 'pending'] );
$result = $this->response( ['text' => 'Done'] )
    ->write( 'Hello' );

use Aimeos\Prisma\Providers\Fake;
use Aimeos\Prisma\Responses\TextResponse;

$fake = new Fake( [
    TextResponse::fromText( 'Hello' ),
    TextResponse::fromText( 'World' ),
] );

$fake->use( new \Aimeos\Prisma\Providers\Text\Myprovider( ['api_key' => 'test'] ) );

$result = $fake->write( 'prompt' );  // returns "Hello"
$result = $fake->write( 'prompt' );  // returns "World"