synapcores/laravel

Laravel integration for the SynapCores AIDB PHP SDK — facade, artisan commands, Eloquent vector cast, RAG trait, and queueable agent jobs

v1.0.0 2026-06-04 12:17 UTC

Requires

• php: ^8.1
• illuminate/console: ^10.0 || ^11.0 || ^12.0
• illuminate/database: ^10.0 || ^11.0 || ^12.0
• illuminate/queue: ^10.0 || ^11.0 || ^12.0
• illuminate/support: ^10.0 || ^11.0 || ^12.0
• synapcores/sdk: ^1.0

Requires (Dev)

• orchestra/testbench: ^8.0 || ^9.0 || ^10.0
• phpunit/phpunit: ^10.5

MIT

• SynapCores

• laravel
• eloquent
• rag
• vector-database
• agentic
• synapcores
• aidb
• ai-database

README

First-class Laravel package on top of synapcores/sdk. Get a SynapCores facade, three artisan commands, an Eloquent vector cast, a RAG trait, and a queueable agent job — all wired to a single config file.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12
• A running SynapCores engine (free CE: docker pull synapcores/community:latest)

Install

composer require synapcores/laravel
php artisan vendor:publish --tag=synapcores-config

Then set in .env:

SYNAPCORES_HOST=localhost
SYNAPCORES_PORT=28080
SYNAPCORES_API_KEY=aidb_…
# or, alternatively:
# SYNAPCORES_USER=admin
# SYNAPCORES_PASSWORD=…

That's it — the service provider auto-registers, the facade auto-loads, the singleton client is shared across your whole app.

Facade

use SynapCores\Laravel\Facades\SynapCores;

$customers = SynapCores::sql('SELECT * FROM customers WHERE id = :id', ['id' => 42]);
foreach ($customers as $row) {
    echo $row['name'], PHP_EOL;
}

$summary = SynapCores::agentRun(
    persona: 'technical_advisor',
    task:    'Summarize the open support tickets.'
);
echo $summary->answer;

Artisan commands

# Quick SQL sanity check
php artisan synapcores:query "SELECT NOW()"

# Format options: table (default), json, csv
php artisan synapcores:query "SELECT * FROM customers LIMIT 5" --format=json

# Fire an agent
php artisan synapcores:agent-run --persona=technical_advisor --task="What changed in v1.7?"

# Import a recipe
php artisan synapcores:recipe-import https://synapcores.com/recipes/churn-prediction.md

Eloquent vector cast

Store embeddings as a VECTOR(N) column; work with float[] in PHP. The cast handles encoding both ways.

use Illuminate\Database\Eloquent\Model;
use SynapCores\Laravel\Eloquent\VectorCast;

class Doc extends Model
{
    protected $casts = [
        'embedding' => VectorCast::class,
    ];
}

// Reads come back as float[]:
$doc = Doc::find(1);
count($doc->embedding); // 384

// Writes accept float[]:
$doc->embedding = SynapCores::embed("hello world");
$doc->save();

HasRAG trait — semantic search returning Eloquent models

use SynapCores\Laravel\Eloquent\HasRAG;

class Doc extends Model
{
    use HasRAG;
    protected $synapcoresEmbeddingColumn = 'embedding'; // optional override
}

// Returns a Collection<Doc>, each with a _score attribute (cosine similarity).
$hits = Doc::ragSearch('how do I reset my password?', k: 5);
foreach ($hits as $doc) {
    echo "[{$doc->_score}] {$doc->title}\n";
}

// With WHERE filters:
$hits = Doc::ragSearch('billing question', k: 10, where: ['lang' => 'en']);

Queue jobs — async agent runs

use SynapCores\Laravel\Jobs\SynapCoresAgentJob;

$job = new SynapCoresAgentJob(
    persona: 'support_summarizer',
    task: 'Summarize all support tickets opened today.',
    opts: ['max_iterations' => 8]
);
dispatch($job);

// Later, fetch the result:
$result = SynapCoresAgentJob::result($job->jobId);
echo $result['answer'];

The job persists its result to the cache under synapcores:agent:{jobId} for 1 hour. For custom persistence, pass a [Class::class, 'method'] tuple as resultHandler.

Configuration reference

All keys are documented in config/synapcores.php. The most-used ones:

.env	Default	Notes
SYNAPCORES_HOST	localhost
SYNAPCORES_PORT	28080
SYNAPCORES_USE_HTTPS	false	Set true in prod
SYNAPCORES_API_KEY	—	aidb_… Bearer key (recommended)
SYNAPCORES_USER	—	For login() flow
SYNAPCORES_PASSWORD	—	For login() flow
SYNAPCORES_DATABASE	—	Sets X-Database header
SYNAPCORES_TENANT	—	Sets X-Tenant header
SYNAPCORES_TIMEOUT	30.0	seconds
SYNAPCORES_QUEUE_CONNECTION	default	Queue connection for the agent job

Engine compatibility

Tested live against SynapCores AIDB v1.7.0.2.1-ce (current :latest, image ghcr.io/synapcores/community:latest). Full integration suite passes through the facade + service container against a real engine. See synapcores-sdks/php/PHP_SDK_PLAN.md in the SDK monorepo for the validation matrix.

License

MIT — see LICENSE.