README

Laravel Nova Tool cu capabilități AI complete: Chat, Generare text, Generare imagini, Analiză vizuală și Gestionare prompt-uri — toate prin OpenRouter.

Cuprins

Cerințe
Instalare
Configurare
Funcționalități
Prompt-uri
Modele suportate
Endpoint-uri API
Logging & Audit
Internaționalizare
Dezvoltare frontend

Cerințe

Dependință	Versiune
PHP	`>= 8.1`
Laravel Nova	`^4.12` sau `^5.0`
Laravel	`^10` sau `^11` sau `^12`
Cont OpenRouter	openrouter.ai

Instalare

1. Instalare pachet

Via Packagist (recomandat pentru producție):

composer require concept24/nova-ai-studio

Dezvoltare locală (symlink):

Dacă vrei să editezi pachetul direct din proiect, adaugă în composer.json al aplicației:

"repositories": [
    {
        "type": "path",
        "url": "./packages/concept24/nova-ai-studio",
        "options": { "symlink": true }
    }
]

composer require concept24/nova-ai-studio:@dev

Composer va crea un symlink în vendor/ către directorul local. Orice modificare este vizibilă instant.

2. Înregistrare Tool în Nova

// app/Providers/NovaServiceProvider.php
use Concept24\NovaAiStudio\NovaAiStudio;

public function tools(): array
{
    return [
        new NovaAiStudio,
    ];
}

3. Publicare resurse și migrații

# Config (recomandat)
php artisan vendor:publish --tag=nova-ai-studio-config

# Migrații (dacă nu se folosesc migrațiile automate)
php artisan vendor:publish --tag=nova-ai-studio-migrations

# Seeders (opțional — pentru a copia seeder-ul local)
php artisan vendor:publish --tag=nova-ai-studio-seeders

# Traduceri (opțional — pentru suprascrieri)
php artisan vendor:publish --tag=nova-ai-studio-lang

4. Rulare migrații

php artisan migrate

Creează tabelele:

nova_ai_studio_logs — audit și tracking costuri
nova_ai_studio_conversations — persistență conversații chat
nova_ai_studio_messages — mesaje chat
nova_ai_studio_prompts — prompt-uri salvate (cu câmpuri for_chat, for_text, for_vision)
nova_ai_studio_video_jobs — job-uri generare video (status, cost, URL temporar)

5. Rulare seeder (opțional — 35 prompt-uri pre-configurate)

php artisan db:seed --class="Concept24\NovaAiStudio\Database\Seeders\AiStudioPromptSeeder"

Seeder-ul folosește updateOrCreate — poate fi rulat repetat fără duplicate.

6. Configurare `.env`

OPENROUTER_API_KEY=sk-or-v1-...

Notă: Dacă cheia lipsește sau este invalidă, tool-ul va afișa un mesaj informativ în loc de tab-uri, fără a genera erori.

Configurare

Fișier: config/nova-ai-studio.php

OpenRouter API

Cheie	Env	Default	Descriere
`openrouter_api_key`	`OPENROUTER_API_KEY`	—	Cheia API OpenRouter (obligatoriu)
`timeout_text`	`OPENROUTER_TIMEOUT_TEXT`	`60`	Timeout (secunde) pentru operații text
`timeout_image`	`OPENROUTER_TIMEOUT_IMAGE`	`180`	Timeout (secunde) pentru generare imagini

Profilul AI al magazinului (opțional)

Cheie	Env	Default	Descriere
`brand_profile.enabled`	`NOVA_AI_STUDIO_BRAND_PROFILE`	`true`	Citește profilul AI al magazinului când aplicația gazdă îl oferă; `false` lasă prompturile neschimbate
`brand_profile.max_chars`	`NOVA_AI_STUDIO_BRAND_PROFILE_MAX_CHARS`	fără plafon	Plafonul textului pentru rolurile `texts` și `translations` (`null`/`0` = fără plafon)
`brand_profile.media_max_chars`	—	`1500`	Textul pentru rolurile `images` și `video` e potrivit la acest plafon

Tab Chat

Cheie	Env	Default	Descriere
`chat.default_model`	`NOVA_AI_STUDIO_CHAT_MODEL`	`openrouter/auto`	Modelul implicit
`chat.max_tokens`	`NOVA_AI_STUDIO_CHAT_MAX_TOKENS`	`4000`	Tokeni maximi per răspuns
`chat.history_limit`	`NOVA_AI_STUDIO_CHAT_HISTORY`	`50`	Mesaje păstrate în context

Web Search (OpenRouter Responses API Beta)

Cheie	Env	Default	Descriere
`web_search.max_results`	`NOVA_AI_WEB_SEARCH_MAX_RESULTS`	`5`	Rezultate (1-25)
`web_search.engine`	`NOVA_AI_WEB_SEARCH_ENGINE`	`null`	Motor: `null`=auto, `native`, `exa`, `firecrawl`, `parallel`
`web_search.include_domains`	—	`[]`	Restricționare la domenii specifice
`web_search.exclude_domains`	—	`[]`	Excludere domenii

Modele Text

'text_models' => [
    'providers' => ['openai', 'anthropic', 'google', 'x-ai', 'perplexity'],
    'families'  => [
        'openai'     => ['mini', 'standard'],
        'google'     => ['flash-lite-preview', 'flash-preview', 'pro-preview'],
        'anthropic'  => ['sonnet', 'opus', 'haiku'],
        'perplexity' => ['sonar-base', 'sonar-pro', 'sonar-deep-research', 'sonar-pro-search'],
        'x-ai'       => ['grok-fast'],
    ],
],

Modele Vision

'vision_models' => [
    'providers'             => ['google', 'openai', 'x-ai', 'anthropic'],
    'default_model'         => 'google/gemini-3-flash-preview',
    'max_completion_tokens' => 1000,
],

Generare Imagini

'image_generation' => [
    'providers'         => ['google', 'openai'],
    'aspect_ratios'     => ['1:1', '16:9', '9:16', '3:4', '4:3', ...],
    'sizes'             => ['0.5K', '1K', '2K', '4K'],
    'max_source_images' => [
        'default'   => 3,
        'per_model' => [
            'google/gemini-3.1-flash-image-preview' => 10,
        ],
    ],
],

Limita de imagini sursă (max_source_images) este expusă per-model în răspunsul /image-models și aplicată atât server-side (în ImageController::generate) cât și în UI (selectorul de upload).

Generare Video (experimental)

'video_generation' => [
    'models' => [
        [
            'id'                   => 'google/veo-3.1',
            'name'                 => 'Google: Veo 3.1',
            'durations'            => [4, 6, 8],
            'resolutions'          => ['720p', '1080p', '4K'],
            'aspect_ratios'        => ['16:9', '9:16'],
            'max_input_references' => 1,
            'supports_audio'       => true,
        ],
        [
            'id'                   => 'bytedance/seedance-1-5-pro',
            'name'                 => 'ByteDance: Seedance 1.5 Pro',
            'durations'            => [4, 5, 6, 7, 8, 9, 10, 11, 12],
            'resolutions'          => ['480p', '720p', '1080p'],
            'aspect_ratios'        => ['16:9', '9:16', '4:3', '3:4', '1:1', '21:9'],
            'max_input_references' => 2,
            'supports_audio'       => true,
        ],
    ],
    'timeout' => 30,
],

Funcționalități

6 Tab-uri

Tab	Descriere
Chat	Conversații AI cu streaming, web search, system prompt, prompt-uri salvate
Text	Generare text cu selector model, stil, prompt template și traducere multi-limbă
Imagini	Generare imagini cu aspect ratio, rezoluție, variante paralele 1–4 și Prompt Template filtrat
Analiză imagine	Upload + analiză vizuală cu prompt template
Video (experimental)	Generare video AI — async job cu polling, video player, download, paginație
Prompt-uri	CRUD complet pentru gestionarea prompt-urilor salvate

Tab Chat

Conversații multiple cu persistență în baza de date
Streaming SSE în timp real
Selector model cu Auto Router (openrouter/auto)
Web Search toggle — activează căutare pe internet via OpenRouter Responses API
System Prompt configurabil per conversație
Prompt-uri salvate — selectare rapidă din lista de prompt-uri (doar citire, fără CRUD)
Grupare conversații: Astăzi / Ieri / Ultimele 7 zile / pe luni
Sidebar colapsabil cu căutare

Tab Text

Prompt Template — dropdown filtrable cu prompt-uri din baza de date (for_text = true), pre-populează textarea
7 stiluri: Neutru, Persuasiv, Conversațional, Profesional, Tehnic, Creativ, SEO Optimizat
Opțiuni avansate: Max tokens (100-2000), Temperatură (0-2)
Traducere multi-limbă post-generare: selecție multiplă, traduceri paralele
- 18 limbi: RO, EN, DE, FR, ES, IT, HU, BG, PL, NL, PT, CS, RU, TR, AR, ZH, JA, KO
Salvare rezultat ca prompt nou

Tab Imagini

Generare din prompt cu selector aspect ratio și rezoluție
Multi-image source upload — limită per model: până la 10 imagini sursă pentru Google Nano Banana 2 (Gemini 3.1 Flash Image Preview), 3 imagini pentru restul modelelor (configurabil în image_generation.max_source_images); grid preview cu ștergere per imagine, suport drag & drop
Variante paralele 1–4 — generează simultan multiple imagini cu același prompt; fiecare variantă folosește un seed random + temperature 0.9 + hint subtil de variație pentru a forța rezultate diferite pe modele deterministe (Gemini Flash Image)
Prompt Template — dropdown filtrabil cu prompt-uri salvate marcate for_image = true, pre-populează textarea
Persistență state cross-tab — galeria, prompt-ul și opțiunile selectate rămân intacte la schimbarea tab-urilor (via <KeepAlive>)
Galerie cu batch grouping — toate imaginile dintr-o generare sunt marcate „NOU" împreună; cost total împărțit egal per imagine pe card
Mesaje de eroare detaliate când modelul refuză (text_reply + finish_reason loggate)
Descărcare directă a imaginilor generate

Tab Video (experimental)

Generare video AI prin OpenRouter Alpha Video API (POST /api/alpha/videos)
Modele suportate: Google Veo 3.1, ByteDance Seedance 1.5 Pro (hardcodate în config)
Parametri per model: durată, rezoluție, aspect ratio, generare audio
Image-to-video — upload imagine referință (1–2 imagini, depinde de model)
Async workflow: submit job → polling la 10s → video ready
Persistență DB — job-urile supraviețuiesc refresh-ului paginii
Buton refresh manual per job pentru verificare status instant
Collapse/expand pe fiecare job card — click afișează prompt complet + video player + download
Paginație — 5 job-uri per pagină
Video player inline cu download proxy (API key nu e expus)
Cost tracking și logging (ACTION_VIDEO_GENERATION)

Tab Analiză Vizuală (Vision)

Upload imagine (max 10MB: JPEG, PNG, WebP, GIF)
Prompt Template — dropdown filtrable cu prompt-uri din baza de date (for_vision = true)
3 niveluri detaliere: Scurt / Mediu / Detaliat
Prompt personalizat opțional

Tab Prompt-uri (CRUD)

Lista cu search text, filtre per scope (Toate / Chat / Text / Vision)
Tabs proprietate: Prompt-urile mele / Partajate
Formular creare/editare cu:
- Titlu + Conținut (max 5000 caractere)
- 3 checkboxuri vizibilitate: Chat, Text, Analiză imagine
- Toggle partajat cu echipa
Vizualizare detalii prompt selectat
Ștergere cu confirmare dialog
Badge-uri vizuale: [Chat] [Text] [Vision] [Partajat]

Profilul AI al magazinului (opțional)

Când aplicația gazdă leagă în container concept24.brand_book (modulul AI Marketing din C24CMS), fiecare tab primește textul propriului rol din profil:

Tab	Rolul	Unde ajunge textul
Text (șabloanele de generare)	`texts`	la finalul promptului de sistem
Text (traducerea)	`translations`	la finalul promptului de sistem al traducătorului
Imagini	`images`	după promptul operatorului, în mesajul trimis modelului
Video	`video`	după promptul operatorului, în cererea trimisă modelului

Promptul operatorului rămâne cel salvat și afișat: VideoJob și răspunsurile păstrează textul scris de operator, profilul se adaugă doar în cererea către model.

Prompturile rămân identice cu cele de dinainte în trei cazuri neutre: aplicația nu oferă binding-ul, profilul nu are text pentru rol sau citirea eșuează (eroarea e raportată, nu aruncată). Textele nu au plafon implicit; un text peste plafon (imaginile și video: 1 500 de caractere) nu se renunță, ci se potrivește: se păstrează liniile întregi de la început și eticheta de închidere, cu o linie info în log. Al patrulea comutator e NOVA_AI_STUDIO_BRAND_PROFILE=false. Fără migrații.

Prompt-uri

Schema baza de date (`nova_ai_studio_prompts`)

Coloană	Tip	Descriere
`title`	`varchar(255)`	Numele prompt-ului
`content`	`text`	Conținutul/instrucțiunile
`for_chat`	`boolean`	Vizibil în tab Chat
`for_text`	`boolean`	Vizibil în tab Text
`for_image`	`boolean`	Vizibil în tab Imagini (v2.4.0+)
`for_vision`	`boolean`	Vizibil în tab Analiză imagine
`is_shared`	`boolean`	Partajat cu echipa
`user_id`	`bigint`	Creatorul prompt-ului

Seeder pre-configurate (35 prompt-uri)

Organizate în 7 categorii:

Marketing Email (7) — promoțional, coș abandonat, welcome, follow-up, reactivare, cerere recenzie, newsletter
Social Media (4) — post IG/FB, script TikTok/Reels, calendar editorial, răspuns comentarii
Ads & Conversie (5) — Google Ads, Meta Ads, banner, push/SMS, popup
SEO & Content (6) — meta title, meta description, keywords, articol blog, descriere categorie, FAQ
Comunicare Clienți (6) — client nemulțumit, review negativ, FAQ, retur, fidelitate, ocazii speciale
Strategie (5) — analiză competitori, campanie sezonieră, brainstorming, UX, plan lansare
Analiză Imagine (2) — descriere detaliată, descriere simplă

Modele suportate

Pachetul filtrează modelele din OpenRouter conform configurării. Lista exactă depinde de abonamentul OpenRouter.

Modele recomandate

Categorie	Model	Motiv
Chat general	`openrouter/auto`	Auto-selectează cel mai potrivit model
Chat rapid	`google/gemini-2.5-flash`	Rapid + ieftin
Raționament	`anthropic/claude-3-5-sonnet`	Calitate înaltă
Imagini	`google/gemini-3-flash-image`	Imagini de calitate
Vision	`google/gemini-3-flash-preview`	Analiză vizuală rapidă
Traduceri	`google/gemini-flash-lite`	Ieftin + rapid

Endpoint-uri API

Toate rutele sunt protejate de middleware-ul Nova (nova, throttle:120,1, Authorize).

Prefix: /nova-vendor/nova-ai-studio/

Metodă	Rută	Descriere
`GET`	`/status`	Verificare stare API key
`GET`	`/models`	Modele text filtrate
`GET`	`/image-models`	Modele generare imagini
`GET`	`/vision-models`	Modele vision
`GET`	`/credits`	Credit rămas OpenRouter
`GET`	`/video-models`	Modele video (din config)
`POST`	`/text/generate`	Generare text
`POST`	`/text/translate`	Traducere text
`POST`	`/image/generate`	Generare imagine
`POST`	`/vision/analyze`	Analiză imagine
`POST`	`/chat/send`	Chat (non-streaming)
`POST`	`/chat/stream`	Chat streaming SSE
`GET`	`/video/jobs`	Lista job-uri video (user curent)
`POST`	`/video/generate`	Submit generare video
`GET`	`/video/status/{jobId}`	Poll status job video
`GET`	`/video/download/{jobId}`	Download video (proxy)
`GET`	`/conversations`	Lista conversații
`POST`	`/conversations`	Creare conversație
`GET`	`/conversations/{id}`	Detalii conversație
`PUT`	`/conversations/{id}`	Actualizare conversație
`DELETE`	`/conversations/{id}`	Ștergere conversație
`GET`	`/prompts`	Lista prompt-uri (own + shared)
`POST`	`/prompts`	Creare prompt
`PUT`	`/prompts/{id}`	Actualizare prompt (owner)
`DELETE`	`/prompts/{id}`	Ștergere prompt (owner)
`GET`	`/logs`	Jurnal utilizare (Super Admin)

Filtre prompt-uri

GET /prompts                  # Toate (own + shared)
GET /prompts?scope=chat       # Doar for_chat=true
GET /prompts?scope=text       # Doar for_text=true
GET /prompts?scope=vision     # Doar for_vision=true

Logging & Audit

Fiecare operație AI este înregistrată automat în tabela nova_ai_studio_logs.

Structura tabelei

Coloană	Tip	Descriere
`cost`	`decimal(12,8)`	Cost USD al operației
`credit_left`	`decimal(12,4)`	Credit rămas (actualizat async)
`action_type`	`varchar(50)`	`text_generation`, `text_translation`, `chat`, `image_generation`, `vision_analysis`, `video_generation`
`model_llm`	`varchar(200)`	ID-ul modelului OpenRouter
`user_id`	`bigint`	ID utilizator
`user_email`	`varchar(255)`	Email utilizator (snapshot)

Utilizare Eloquent

use Concept24\NovaAiStudio\Models\AiStudioLog;

AiStudioLog::where('user_id', $userId)->latest()->get();
AiStudioLog::whereMonth('created_at', now()->month)->sum('cost');
AiStudioLog::where('action_type', AiStudioLog::ACTION_CHAT)->count();

Internaționalizare

Limbi incluse: RO (implicit), EN, DE, FR, ES.

# Publică pentru suprascriere
php artisan vendor:publish --tag=nova-ai-studio-lang

Editează: resources/lang/vendor/nova-ai-studio/{locale}.json

Dezvoltare frontend

Pachetul folosește Vue 3 cu Element Plus, compilat prin Nova Mix.

Structura resurse

resources/
├── js/
│   ├── tool.js                 # Entry point
│   ├── pages/
│   │   └── AiStudio.vue        # Pagina principală (5 tabs + API key check)
│   ├── components/
│   │   ├── CreditsBar.vue
│   │   ├── TabNav.vue          # Chat, Text, Imagini, Analiză imagine, Video, Prompt-uri
│   │   ├── tabs/
│   │   │   ├── ChatTab.vue
│   │   │   ├── TextTab.vue
│   │   │   ├── ImageTab.vue
│   │   │   ├── VisionTab.vue
│   │   │   ├── VideoTab.vue    # Generare video (experimental)
│   │   │   └── PromptsTab.vue  # CRUD prompt-uri
│   │   ├── chat/
│   │   │   ├── ChatMessage.vue
│   │   │   └── StreamingIndicator.vue
│   │   └── shared/
│   │       ├── ModelSelector.vue
│   │       ├── CopyButton.vue
│   │       ├── PromptPanel.vue # Modal prompt-uri (folosit din TextTab)
│   │       └── MarkdownRenderer.vue
│   └── utils/
├── css/
│   └── tool.css                # Variabile CSS, dark mode
└── lang/                       # Traduceri (ro, en, de, fr, es)

Securitate

Toate rutele necesită autentificare Nova (Authorize middleware)
Validare model_id față de lista albă configurată
Sanitizare input (strip_tags, mb_substr)
Rate limiting: 120 request/minut per IP
Credentiale API exclusiv prin variabile de mediu
Verificare API key la încărcare — mesaj informativ dacă lipsește/e invalidă

Istoric versiuni

Versiune	Data	Modificări
2.5.0	2026-10-28	Profilul AI al magazinului: când aplicația gazdă leagă `concept24.brand_book` (modulul AI Marketing din C24CMS), fiecare tab primește textul rolului său din profil (texte, traduceri, imagini, video), adăugat doar în cererea către model; promptul operatorului rămâne cel salvat. Textele și traducerile n-au plafon implicit (`brand_profile.max_chars`), un text peste plafon e potrivit la rânduri întregi, nu tăiat; imaginile și video-ul la `brand_profile.media_max_chars` (1500). O citire eșuată a profilului e raportată o singură dată pe cerere și lasă prompturile neschimbate. Fără migrare
2.4.1	2026-10-12	Securitate: pagina tool-ului (`/nova-ai-studio`) se randa fără login (`Nova::router()` aplica doar `nova.middleware`), iar API-ul depindea doar de `canSee` al tool-ului (un vizitator îl făcea să crape cu 500 în loc de 401). Pagina e acum pe `nova` + `Authenticate` Nova + `viewNova` + `Authorize` al tool-ului; API-ul pe `nova:api` + `Authorize`. Vizitator → redirect la login / 401; utilizator Nova fără `canSee` → 403.
2.4.0	2026-05-21	Tab Imagini: limită `max_source_images` per model (10 pentru Gemini 3.1 Flash Image), variante paralele 1–4 cu seed + temperature + hint de variație, dropdown Prompt Template filtrat (`for_image`), persistență state cross-tab via `<KeepAlive>`. Prompts: nouă coloană `for_image` + scope `image` în API. Logging detaliat când modelul nu returnează imagini.
2.3.0	2026-04	Image meta revamp, layout fixes, video & image model updates
2.2.x	2026-04	Video tab improvements, delete jobs
2.1.0	2026-04	Multi-image upload (până la 3 imagini sursă)
2.0.x	2026-03	Release inițial v2

concept24 / nova-ai-studio

Package info

Security

Statistics

README

Cuprins

Cerințe

Instalare

1. Instalare pachet

2. Înregistrare Tool în Nova

3. Publicare resurse și migrații

4. Rulare migrații

5. Rulare seeder (opțional — 35 prompt-uri pre-configurate)

6. Configurare .env

Configurare

OpenRouter API

Profilul AI al magazinului (opțional)

Tab Chat

Web Search (OpenRouter Responses API Beta)

Modele Text

Modele Vision

Generare Imagini

Generare Video (experimental)

Funcționalități

6 Tab-uri

Tab Chat

Tab Text

Tab Imagini

Tab Video (experimental)

Tab Analiză Vizuală (Vision)

Tab Prompt-uri (CRUD)

Profilul AI al magazinului (opțional)

Prompt-uri

Schema baza de date (nova_ai_studio_prompts)

Seeder pre-configurate (35 prompt-uri)

Modele suportate

Modele recomandate

Endpoint-uri API

Filtre prompt-uri

Logging & Audit

Structura tabelei

Utilizare Eloquent

Internaționalizare

Dezvoltare frontend

Structura resurse

Securitate

Istoric versiuni

Licență

6. Configurare `.env`

Schema baza de date (`nova_ai_studio_prompts`)