kozmonos/laravel-vertex-ai

Laravel bridge for kozmonos/vertex-ai: service provider, managers, Eloquent batch helpers, and S3 reference image loading.

Install

composer require kozmonos/laravel-vertex-ai
php artisan vendor:publish --tag=vertex-ai-config

Packages are published on Packagist. For local development of both vertex-ai and this bridge, add path repositories in your app's composer.json (not required for normal installs).

Environment

VERTEX_FORCED_ACCESS_TOKEN is ignored outside local and testing.

Managers

use Kozmonos\LaravelVertexAi\Managers\TextGenerationManager;
use Kozmonos\LaravelVertexAi\Managers\VideoGenerationManager;

app(TextGenerationManager::class)->driver()->generateText(...);

// Image → video: pass a loadable URL (HTTP/MinIO/data) or gs:// — the package loads bytes + mime.
app(VideoGenerationManager::class)->driver()->generateVideo(
    prompt: 'Slow push-in',
    modelId: 'veo-3.1-fast-vertex',
    durationSeconds: 4,
    options: ['source_image_url' => $imageAssetDisplayUrl],
);

In testing, register fake drivers automatically (config('vertex-ai.text.default') = 'fake').

Eloquent batch polling / cancel

use Kozmonos\LaravelVertexAi\Batch\Actions\PollSingleVertexBatchJobAction;
use Kozmonos\LaravelVertexAi\Batch\Concerns\HasVertexBatchJobRecord;

// Model implements VertexBatchJobRecord via HasVertexBatchJobRecord trait

app(PollSingleVertexBatchJobAction::class)->execute($job, lockPrefix: 'vertex-batch');

Usage recording

Bind your app recorder to Kozmonos\VertexAi\Contracts\UsageRecorder after LaravelVertexAiServiceProvider. Extend AbstractEloquentUsageRecorder for Eloquent persistence with automatic cost calculation from kozmonos/vertex-ai pricing.

// Before (callback wrapper)
AiUsageContext::run($frame, fn () => $provider->generateText(...));

// After (Laravel Context — no callback)
use Kozmonos\LaravelVertexAi\Facades\AiUsage;

AiUsage::for($youtubeItem, $project);
$result = app(TextGenerationManager::class)->driver()->generateText(...);

Scope resolvers (organization/project) register via the vertex-ai.usage_scope_resolvers tag. Usage is on by default; disable with VERTEX_AI_USAGE_ENABLED=false.

AiUsage::batch(); // mark subsequent calls as batch-priced
AiUsage::fake();  // swap to NullUsageRecorder in tests
AiUsage::flush(); // clear context between tests

Publish the migration stub:

php artisan vendor:publish --tag=vertex-ai-migrations

Fluent Ai gateway (optional)

use Kozmonos\LaravelVertexAi\Facades\Ai;

Ai::for($item, $project)->text()->generate(...);

Custom usage recording

Bind your app implementation to Kozmonos\VertexAi\Contracts\UsageRecorder in a service provider after LaravelVertexAiServiceProvider.

Security

Read SECURITY.md and the core package SECURITY.md.

Tests

composer install
composer test
composer analyse

License

MIT. See LICENSE.