kozmonos/laravel-vertex-ai

Laravel bridge for kozmonos/vertex-ai

1.1.1 2026-07-21 19:37 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^12.0|^13.0
• illuminate/support: ^12.0|^13.0
• kozmonos/vertex-ai: ^1.2

Requires (Dev)

• orchestra/testbench: ^10.0
• pestphp/pest: ^4.0
• phpstan/phpstan: ^2.0

MIT

• Kozmonos

• laravel
• ai
• Gemini
• google-cloud
• vertex-ai

Published on Packagist.org on 2026-07-21 19:37 UTC

README

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

Variable	Purpose
VERTEX_PROJECT_ID	GCP project
VERTEX_CREDENTIALS_PATH	Service account JSON
VERTEX_BATCH_GCS_BUCKET	Batch input/output bucket
VERTEX_FORCED_ACCESS_TOKEN	Local/testing auth override only
AI_OUTBOUND_ALLOWED_HOSTS	Comma-separated host allowlist for reference image downloads
DEEPGRAM_API_KEY	STT

VERTEX_FORCED_ACCESS_TOKEN is ignored outside local and testing.

Managers

use Kozmonos\LaravelVertexAi\Managers\TextGenerationManager;

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

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.