README

evo-ai for Evolution CMS

evo-ai is an Evolution CMS library that integrates Laravel AI SDK capabilities into Evolution-based projects. It provides Evo‑native config publishing, minimal shims for missing Illuminate\Foundation classes, and an sTask‑first queue bridge.

If you only need a quick start and examples, use this README. For full details see DOCS.md (EN) or DOCS.uk.md (UA).

Requirements

• Evolution CMS 3.5+
• PHP 8.3+
• Composer 2.2+

Optional:

• sTask for async tasks (package constraint: ^1.0)

Quick Start

From your Evo core directory:

cd core
php artisan package:installrequire evolution-cms/evo-ai "*"
php artisan migrate

Publish configs and stubs (optional, auto‑publish is enabled):

php artisan vendor:publish --provider="EvolutionCMS\\eAi\\eAiServiceProvider" --tag=eai-config
php artisan vendor:publish --provider="EvolutionCMS\\eAi\\eAiServiceProvider" --tag=eai-ai-config
php artisan vendor:publish --provider="EvolutionCMS\\eAi\\eAiServiceProvider" --tag=eai-stubs

Set provider key in .env or core/custom/config/ai.php:

OPENAI_API_KEY=...

Run the built‑in smoke test:

php artisan ai:test

For local Ollama:

php artisan ai:test --provider=ollama

Minimal Usage

use App\Ai\Agents\SupportAgent;

$agent = new SupportAgent();
$response = $agent->prompt('Hello from Evo');

echo $response->text;

Queues (sTask‑first)

• sTask is the primary backend; sync is a fallback.
• eAi does not implement Laravel Queue; it only provides SDK‑compatible dispatching.

Process queued tasks:

php artisan stask:worker

sTask UI workers (for testing):

• eai_smoke — fixed prompt
• eai_prompt — custom prompt from widget

AI Service Account (Role‑based)

AI runs as a normal manager user with role AI (auto‑created). The role is read‑only by default; to allow saving/publishing, elevate permissions manually (e.g. Publisher).

Example settings in core/custom/config/cms/settings/eAi.php:

ai_actor_mode: service
ai_actor_email: ai@your-host
ai_actor_autocreate: true
ai_actor_block_login: true
ai_actor_role: AI
ai_actor_role_autocreate: true

If you need access to package interfaces, grant permissions stask and/or sapi to the AI role (grouped under sPackages).

Artisan Generators

php artisan make:agent SalesCoach
php artisan make:agent SalesCoach --structured
php artisan make:tool RandomNumberGenerator

Generated classes are placed in core/custom/app/Ai/.... If autoloading is not updated, run composer dumpautoload.

More Details

See DOCS.md for full configuration reference, identity rules, queue contract, and advanced SDK usage.