concept24 / nova-ai-report
KPI Reports tool for Laravel Nova — daily/weekly/monthly analytics dashboards for e-commerce.
Requires
- php: ^8.2
- laravel/framework: ^11.0|^12.0|^13.0
- laravel/nova: ^4.12|^5.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
KPI Reports & BI Agent tool for Concept24 CMS — daily/weekly/monthly analytics dashboards and AI-powered chat for e-commerce, built on Laravel Nova.
Requirements
- PHP 8.2+
- Laravel 11, 12 or 13
- Laravel Nova 4.12+ / 5.x
- OpenRouter API key
Installation
composer require concept24/nova-ai-report
The service provider is auto-discovered. Migrations run automatically via loadMigrationsFrom. Publish config manually:
php artisan vendor:publish --tag=nova-ai-report-config
To copy migrations into your app's database/migrations/ (optional):
php artisan vendor:publish --tag=nova-ai-report-migrations
To seed the default prompt library (30 standard e-commerce reports):
php artisan db:seed --class="Concept24\NovaAiReport\Database\Seeders\AiReportPromptSeeder"
Configuration
config/nova-ai-report.php (takes full priority over package defaults):
| Key | Env var | Default |
|---|---|---|
openrouter.api_key | OPENROUTER_API_KEY | — |
default_model | NOVA_AI_REPORT_DEFAULT_MODEL | ~anthropic/claude-opus-latest |
models.primary | NOVA_AI_REPORT_MODEL_PRIMARY | ~anthropic/claude-sonnet-latest |
models.fast | NOVA_AI_REPORT_MODEL_FAST | google/gemini-3-flash-preview |
models.reasoning | NOVA_AI_REPORT_MODEL_REASONING | ~anthropic/claude-opus-latest |
max_tool_iterations | NOVA_AI_REPORT_MAX_TOOL_ITERATIONS | 60 |
max_tokens | NOVA_AI_REPORT_MAX_TOKENS | 32000 |
reasoning_effort | NOVA_AI_REPORT_REASONING_EFFORT | medium |
brief_reasoning_effort | NOVA_AI_REPORT_BRIEF_REASONING_EFFORT | high (briefuri cu ≥3 puncte) |
brief_max_tokens | NOVA_AI_REPORT_BRIEF_MAX_TOKENS | 64000 |
max_continuations | NOVA_AI_REPORT_MAX_CONTINUATIONS | 3 (răspuns tăiat la max_tokens → continuare automată) |
stream_retries / stream_retry_delay | NOVA_AI_REPORT_STREAM_RETRIES / …_RETRY_DELAY | 2 / 5 s (erorile 400–404/413 nu se reiau) |
max_run_seconds | NOVA_AI_REPORT_MAX_RUN_SECONDS | 1800 (ridică limita Octane de 30 s pe stream) |
connection | NOVA_AI_REPORT_DB_CONNECTION | conexiunea implicită (BI pe altă bază) |
cache_ttl | NOVA_AI_REPORT_CACHE_TTL | 300 |
rate_limit | NOVA_AI_REPORT_RATE_LIMIT | 30,1 |
Minimum .env:
OPENROUTER_API_KEY=sk-or-...
Database
Tables
| Table | Purpose |
|---|---|
nova_ai_report_conversations | BI Agent chat sessions (user_id, title, model, model_tier) |
nova_ai_report_messages | Chat messages (role, content, tool_calls, query_results) |
nova_ai_report_logs | Per-request usage tracking (tokens, cost, latency, tool_calls_count) |
nova_ai_report_prompts | Global saved prompt library (title, content, sort_order) |
Prompts table
nova_ai_report_prompts
id bigint PK
title varchar(255)
content text (max 5000 chars)
sort_order int (default 0)
created_at timestamp
updated_at timestamp
Prompts are global — no user ownership, no sharing flags. All Nova users share the same library.
Seeder
AiReportPromptSeeder ships 30 standard e-commerce report prompts in Romanian, organized by category:
| Category | Prompts |
|---|---|
| Vânzări & Venituri | 6 — revenue, product/category sales, AOV, vouchers, returns, profitability |
| Comportament Utilizatori | 5 — conversion rate, funnel, cart abandonment, page performance, site search |
| Clienți & Loialitate | 7 — new vs. returning, CLV, cohort retention, repeat purchase, RFM, churn risk, reviews |
| Produse & Stoc | 6 — bestsellers/worst performers, critical stock, replenishment, dead stock, cross-sell, wishlist |
| Operațional & Logistică | 3 — order status, delivery performance, payment methods |
| Financiar & Strategic | 3 — executive dashboard, net profitability after returns, 6-month strategic trend |
Excludes: GA4, Google Ads, Meta/TikTok, Hotjar/Clarity — uses only internal database data.
Features
KPI Dashboards
Tab-based dashboards over the kpi_* tables of the host app's Kpi module. When the module is off or its tables are missing, the KPI tabs show an explanatory empty state instead of failing (EnsureKpiAvailable middleware answers {"available": false}); the BI Agent keeps working on the shop tables. UI translated in Romanian and English (resources/lang/{ro,en}.json, loaded with Nova::translations).
| Tab | Data source | What it shows |
|---|---|---|
| Overview | daily rollups + kpi_events | KPI cards vs. previous period, sales channels (AI assistant, AI-referred traffic) |
| Realtime | kpi_events, kpi_sessions | last 30 minutes, auto-refresh every 30 s while the tab is open: active users now (5 min) / in 30 min, page views per minute, sources, devices, top events, pages being viewed (title, path, views, active now); no date picker |
| Sales | kpi_daily_sales, site_orders, kpi_abandoned_carts | revenue, orders, conversion %, cart abandonment % (from cart events); block „Abandoned and recovered carts” (abandoned count / value, recovered count / value, recovery rate overall and with / without the reminder email, vs. previous period; hidden without the kpi_abandoned_carts table) |
| Traffic | kpi_daily_traffic, kpi_sessions | sessions, sources and mediums; "Technology and language": sessions, orders, conversion and revenue by browser, OS, screen resolution (top 10), browser language and site language (from kpi_sessions, no location / IP) |
| Acquisition | kpi_daily_traffic, kpi_sessions, kpi_events | KPI cards vs. previous period (sessions, orders, conversion, revenue, revenue per session, new users, leads); channels (source / medium) and campaigns (utm_campaign) with sessions, orders, conversion and revenue (cost / ROAS / cost per order columns appear only when cost data exists); new users by the source of their first visit (needs kpi_sessions.cookie_id); leads (sign_up, newsletter_signup, contact_form_submit) by source with a daily trend |
| Pages | kpi_daily_pages (rollup), kpi_events for the drill-down | sortable, searchable, paginated table with each figure's share of the total; switch between Viewed pages (views, users, views per user, avg. engagement time, 75% scroll, clicks, key events) and Landing pages (entrances, bounce rate, key-event rate, orders, revenue); daily chart with a Total line plus the ticked rows (default top 5). Click a row for the page detail (raw kpi_events for that path): daily trend, scroll 25/50/75/100%, clicks by type, content bands (views, clicks, click rate, position), most clicked products, cart / order conversion of the sessions that saw the page. Users are distinct over the period, computed from kpi_events for the rows shown (so the user-based columns are not sortable); revenue is attributed to the session's landing page |
| Events | kpi_daily_events (rollup), kpi_events for distinct users and the detail | every event of the period: label, domain, count (share of total, change vs. previous period), sessions, distinct users (cached cache_ttl), per user; daily chart with the ticked rows (default top 5); click an event for its daily trend, page types, source / medium and top products. With a segment active everything is computed from kpi_events |
| Behaviour (UX) | kpi_daily_ux, kpi_events | scroll reach per page type (50/75/100%), repeated (rage) clicks, content bands most viewed / seen but ignored, filters used, pagination depth; Navigation from the menu: most used links of the main menu (label, path, clicks, visits), share of visits that use the menu, desktop vs mobile (menu_click; the platform stamps data-kpi-menu on the header links) |
| Products | kpi_daily_products, site_products, kpi_events | views, add-to-cart, purchases per product; Click rate in lists: per product how often it was seen in category / search / band lists (view_item_list), clicks, click rate and average position (rollup columns list_impressions, list_clicks, avg_list_position), top "seen a lot, clicked little", breakdown by type of list; the segment bar applies to this block only |
| Search | kpi_events | top terms with click-through rate, searches without results, daily trend; Reworded searches (computed, no new event): share of visits that searched a different term within 5 minutes, top "term → next term" pairs, and whether the rewording led to a result click |
| Retention | site_orders, kpi_sessions | customers from orders (new vs returning with revenue, repurchase rate, median days to the 2nd order, monthly cohorts with % who ordered again, cumulative lifetime value per customer, top customers by lifetime value — IDs only, no personal data); visitors from kpi_sessions.cookie_id (new vs returning per day, return after 1 / 7 / 30 days, weekly cohorts). The customers part works even with the Kpi module off |
| Funnels | kpi_daily_funnels, kpi_events | stylised SVG funnel (share of first step, step conversion, biggest drop); funnels incl. checkout steps and AI Assistant → Cart; block „Where customers get stuck” under the funnels: top checkout_error reasons (step + field + reason, attempts, visits affected — field names only, never typed values) |
Segment bar (under the date picker, shared by all tabs and kept when switching tabs): device, new / returning visitors, source / medium. On the tabs where the bar is active (Realtime, Acquisition, Pages, Behaviour, Search, Events, Retention) the segment applies to everything shown, computed from kpi_events / kpi_sessions instead of the daily rollups (cached per period + segment where heavy); what cannot be split (campaign costs, customers from orders) says so next to the block. Tabs built on rollups without these dimensions (Overview, Sales, Traffic, Funnels) do not show the bar at all; on Products the bar applies only to the Click rate in lists block (computed from kpi_events while a segment is active), the rest of the tab stays on all visitors and says so. Values are whitelisted (Http/Support/Segment.php) and bound as parameters.
Internal traffic: sessions / events of visitors seen signed in with a Nova-access user are flagged at ingest and left out of the aggregators and of every raw query (Http/Support/KpiQuery.php) while kpi.exclude_internal (KPI_EXCLUDE_INTERNAL, default true) is on.
BI Agent Chat
AI-powered chat that queries operational and KPI tables via a tool-call loop.
- Multi-turn conversation with tool calls:
execute_sql,get_table_schema,get_join_pattern,get_entity_links,get_report_recipe - Multi-model picker: Gemini Flash/Pro, OpenAI (Astra, Sol, Terra, Mini), Claude (Sonnet, Opus, Fable), Grok, Kimi — OpenRouter „latest” aliases
- SSE real-time streaming with animated typing indicator
- Silent retry on failed tool calls
- Per-conversation cost display
- Conversation management: rename, delete, search, multi-tab
- Report mode: when the question asks for a report, an analysis or a decision, the answer is structured — summary with Δ% vs. the previous period, indicators table, what explains the change, anomalies, at most 3 recommendations tied to figures, data limits. Quick questions stay short
- Analytical rigour in the system prompt: source of truth per figure (orders/customers from the shop tables, traffic/behaviour from
kpi_*), KPI coverage start, small samples, totals check, visitors without an identifier, test / internal orders (domains of admin accounts), ranking criterion, no unproven technical diagnoses; the KPI rollups (kpi_daily_pages,kpi_daily_events,kpi_campaign_costs) with usage rules and example SQL. Measured on 12 questions with a blind judge: 110 → 134 / 144 - Safe Markdown (
resources/js/utils/markdown.js): raw HTML from model answers is escaped, links onlyhttp(s),mailto, relative and anchors, images only same-site relative paths (no external image loads);node resources/js/utils/markdown.test.mjsruns the XSS payload checks
Routing: all BI Agent endpoints are prefixed /nova-vendor/nova-ai-report/bi-agent/ and protected by Nova + Authorize middleware.
| Method | Path | Description |
|---|---|---|
POST | chat | Stream a response (SSE) |
GET | config | Available models, defaults, KPI table presence |
GET | credits | OpenRouter credit balance |
GET | usage | Per-day usage stats |
GET/POST | conversations | List / create |
GET/PATCH/DELETE | conversations/{id} | Show / update / delete |
GET/POST | prompts | List / create prompts |
PATCH/DELETE | prompts/{id} | Update / delete prompt |
POST | export | Generate HTML export |
Saved Prompts
Global library of reusable prompt templates accessible from two entry points:
- Prompts tab — split-panel management UI (CRUD, search, inline edit)
- ⚡ button in ChatInput — modal picker that inserts prompt content into the textarea
Chat Export
Selective export of agent responses to a self-contained HTML file.
- Click the ↓ button in the tab bar to enter selection mode
- Checkboxes appear on each exportable message (text + charts/tables)
- Transitional inter-tool notes are excluded from export automatically
- Click Export HTML —
html2canvascaptures chart messages as PNG screenshots; text messages export as real HTML - Downloads as
{conversation-title}.html
Architecture
Backend
src/
Http/
Controllers/
BiAgentController.php — chat, config, credits, usage
ConversationController.php — conversation CRUD
PromptController.php — prompt CRUD
ExportController.php — HTML export
OverviewController.php / SalesController.php / TrafficController.php / UxController.php /
ProductsController.php / SearchController.php / FunnelsController.php /
RealtimeController.php / PagesController.php — KPI tab APIs (`/realtime`, `/pages`, `/pages/plot`, `/pages/detail?path=`)
RetentionController.php — `/retention/customers` (from orders, outside EnsureKpiAvailable) and `/retention/visitors` (from kpi_sessions, answers `{available:false}` itself)
Middleware/
EnsureKpiAvailable.php — `{"available": false}` when the Kpi tables are missing
Support/
KpiTables.php — Kpi module availability check
Services/
BiAgentOrchestrator.php — tool-call loop
ChatExportService.php — HTML export generation
KpiSchemaProvider.php — system prompt + schema introspection
KpiQuerySanitizer.php — SQL safety (one SELECT/WITH statement, no executable comments / SLEEP / BENCHMARK / LOAD, sensitive column masking)
NovaReportRecipes.php — CMS report SQL recipes
OpenRouterClient.php — SSE streaming client
Models/
Conversation.php
Message.php
AiReportLog.php
Prompt.php
Frontend (Vue 3 Composition API)
resources/js/
pages/
AiReport.vue — root page, tab routing
components/
tabs/
BiAgentTab.vue — chat UI, export orchestration
PromptsTab.vue — prompt management (split panel)
UsageTab.vue
OverviewTab.vue / SalesTab.vue / TrafficTab.vue / UxTab.vue / ProductsTab.vue / SearchTab.vue / FunnelsTab.vue / RealtimeTab.vue / PagesTab.vue / RetentionTab.vue
KpiFunnelChart.vue — SVG funnel
KpiUnavailable.vue — empty state when the Kpi module is off
DataTable.vue — simple table for the behaviour / search blocks
utils/
i18n.js — t() over Nova translations
bi-agent/
ChatThread.vue — message list
BiAgentMessage.vue — single message (text / chart / export checkbox)
BiAgentResultChart.vue — chart/table renderer (Chart.js)
ChatInput.vue — textarea + model picker + ⚡ prompts button
ExportBar.vue — export mode action bar
PromptPickerModal.vue — modal prompt selector
CSS
All component styles in resources/css/tool.css using --ai-* CSS variables scoped to .nova-ai-report-wrap. Dark mode via .dark .nova-ai-report-wrap.
Changelog
| Version | Date | Notes |
|---|---|---|
| 1.8.0 | 2026-11-11 | Securitate (validatorul SQL al BI Agent): o singură instrucțiune pe interogare — refuzată orice a doua instrucțiune după ; (ex. SELECT 1; SET …, SELECT 1; DO SLEEP(10)), refuzate comentariile executabile MySQL /*! … */, SLEEP(), BENCHMARK(), LOAD DATA / LOAD XML; comentariile obișnuite nu mai declanșează refuzuri false. Rapoarte noi: „Coșuri abandonate și recuperate” în Vânzări, „Navigarea din meniu” în Comportament, „Rata de click în liste” în Produse, căutări reformulate în Căutare, „Unde se blochează clienții” sub Pâlnii |
| 1.7.0 | 2026-11-06 | Rapoarte în stilul GA: tab-uri noi „Timp real”, „Achiziție” (canale, campanii cu cost / ROAS / cost per comandă, utilizatori noi pe prima sursă, lead-uri), „Pagini” (vizualizate / de intrare, grafic cu rânduri bifate, detaliu cu benzi, derulare, clickuri, conversie), „Evenimente”, „Retenție” (clienți din comenzi: cohorte, valoare pe viață; vizitatori: revenire z1/z7/z30), „Tehnologie și limbă” în Trafic; bara de segmente (dispozitiv, noi / reveniți, sursă / mediu) pe tab-urile unde se aplică; trafic intern exclus; titluri de secțiune cu notă (SectionHeading), panouri cu plăci, pâlnii compacte; BI Agent: mod raport + rigoare analitică (evaluare oarbă 110 → 134 / 144) și Markdown sigur (fără HTML brut, fără imagini externe) |
| 1.6.0 | 2026-11-06 | KPI v2: tab nou „Căutare” (termeni de top cu rata de click, căutări fără rezultate); „UX” → „Comportament” (derulare pe tip de pagină, clickuri repetate, benzi de conținut văzute/ignorate, filtre, paginare); pâlnie SVG stilizată + pâlnia Asistent AI → Coș; canalele de vânzare în Prezentare și în BI Agent (asistentul AI, trafic din asistenți AI); conversie și abandon coș ca procente; ecran explicativ când modulul Kpi lipsește; interfață tradusă RO/EN; comparație cu perioada anterioară pe carduri |
| 1.5.1 | 2026-10-19 | Compatibilitate Laravel 11, 12 și 13 (laravel/framework ^11.0\|^12.0\|^13.0); PHP minim 8.2 |
| 1.5.0 | 2026-10-15 | Briefuri mari în etape: protocol de acoperire (tabel „Acoperire”), reasoning effort high + 64K pentru briefuri, continuare automată la max_tokens, o trecere de completare pentru punctele neverificate, sinteză la epuizarea pașilor, retry la erori de rețea, heartbeat SSE la 10 s, max_run_seconds; fix pierdere text lângă emoji (✅) și tokeni „0”; conexiune BI configurabilă; model implicit Opus latest |
| 1.4.13 | 2026-10-13 | Kimi (latest) grupat sub furnizorul Moonshot, alături de Kimi K2 |
| 1.4.12 | 2026-10-13 | Modele: aliasuri „latest” Gemini Flash, Gemini Pro și Kimi (Moonshot AI) |
| 1.4.11 | 2026-10-13 | Modele: aliasuri OpenRouter „latest” pentru OpenAI (Astra, Sol, Terra, Mini), Anthropic (Sonnet, Opus, Fable) și xAI (Grok); implicit Sonnet/Opus latest |
| 1.4.10 | 2026-10-12 | Security: the tool page (/nova-ai-report) rendered without login (Nova::router() applied only nova.middleware) and the API relied only on the tool's canSee (a guest crashed it with a 500 instead of a 401). Page now on nova + Nova Authenticate + viewNova + the tool's Authorize; API on nova:api + Authorize. Guests get a redirect to the Nova login / 401, Nova users failing canSee get 403 |
| 1.4.8 | 2026-05-19 | Fix UX/Traffic/Products tab KPI cards reading wrong API key (current → kpis.*.current); fix product name resolution (use title accessor instead of name); add utils/labels.js with human-readable labels for events/funnels/steps/page types; funnel chart improvements (wider labels, more spacing, value pill visible on both filled and empty bars) |
| 1.3.1 | 2026-05-02 | Fix o3/o1 temperature error (reasoning models skip temperature, use max_completion_tokens); increase max_tokens 4096→16384; compress large tool results in conversation history (first 60 rows); error/timeout messages survive loadTabMessages reload |
| 1.3.0 | 2026-04-30 | Migrations bundled in package; AiReportPromptSeeder (30 e-commerce reports); KPI tabs auto-hidden; Romanian terminology; operational tables priority; table overflow fix |
| 1.2.0 | 2026-04-30 | Chat export to HTML (html2canvas); nudge/retry chips; transitional message styling |
| 1.1.0 | 2026-04-29 | Saved Prompts (global library + modal picker + management tab) |
| 1.0.0 | 2026-04-29 | Initial release — BI Agent chat, KPI dashboards, model picker, usage tracking |