Search by

concept24 / nova-ai-report

mihaictinescu

KPI Reports tool for Laravel Nova — daily/weekly/monthly analytics dashboards for e-commerce.

Package info

bitbucket.org/concept24/nova-ai-report

pkg:composer/concept24/nova-ai-report

Statistics

Installs: 90

Dependents: 0

Suggesters: 0

v1.8.0 2026-11-11 05:32 UTC

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):

KeyEnv varDefault
openrouter.api_keyOPENROUTER_API_KEY—
default_modelNOVA_AI_REPORT_DEFAULT_MODEL~anthropic/claude-opus-latest
models.primaryNOVA_AI_REPORT_MODEL_PRIMARY~anthropic/claude-sonnet-latest
models.fastNOVA_AI_REPORT_MODEL_FASTgoogle/gemini-3-flash-preview
models.reasoningNOVA_AI_REPORT_MODEL_REASONING~anthropic/claude-opus-latest
max_tool_iterationsNOVA_AI_REPORT_MAX_TOOL_ITERATIONS60
max_tokensNOVA_AI_REPORT_MAX_TOKENS32000
reasoning_effortNOVA_AI_REPORT_REASONING_EFFORTmedium
brief_reasoning_effortNOVA_AI_REPORT_BRIEF_REASONING_EFFORThigh (briefuri cu ≥3 puncte)
brief_max_tokensNOVA_AI_REPORT_BRIEF_MAX_TOKENS64000
max_continuationsNOVA_AI_REPORT_MAX_CONTINUATIONS3 (răspuns tăiat la max_tokens → continuare automată)
stream_retries / stream_retry_delayNOVA_AI_REPORT_STREAM_RETRIES / …_RETRY_DELAY2 / 5 s (erorile 400–404/413 nu se reiau)
max_run_secondsNOVA_AI_REPORT_MAX_RUN_SECONDS1800 (ridică limita Octane de 30 s pe stream)
connectionNOVA_AI_REPORT_DB_CONNECTIONconexiunea implicită (BI pe altă bază)
cache_ttlNOVA_AI_REPORT_CACHE_TTL300
rate_limitNOVA_AI_REPORT_RATE_LIMIT30,1

Minimum .env:

OPENROUTER_API_KEY=sk-or-...

Database

Tables

TablePurpose
nova_ai_report_conversationsBI Agent chat sessions (user_id, title, model, model_tier)
nova_ai_report_messagesChat messages (role, content, tool_calls, query_results)
nova_ai_report_logsPer-request usage tracking (tokens, cost, latency, tool_calls_count)
nova_ai_report_promptsGlobal 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:

CategoryPrompts
Vânzări & Venituri6 — revenue, product/category sales, AOV, vouchers, returns, profitability
Comportament Utilizatori5 — conversion rate, funnel, cart abandonment, page performance, site search
Clienți & Loialitate7 — new vs. returning, CLV, cohort retention, repeat purchase, RFM, churn risk, reviews
Produse & Stoc6 — bestsellers/worst performers, critical stock, replenishment, dead stock, cross-sell, wishlist
Operațional & Logistică3 — order status, delivery performance, payment methods
Financiar & Strategic3 — 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).

TabData sourceWhat it shows
Overviewdaily rollups + kpi_eventsKPI cards vs. previous period, sales channels (AI assistant, AI-referred traffic)
Realtimekpi_events, kpi_sessionslast 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
Saleskpi_daily_sales, site_orders, kpi_abandoned_cartsrevenue, 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)
Traffickpi_daily_traffic, kpi_sessionssessions, 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)
Acquisitionkpi_daily_traffic, kpi_sessions, kpi_eventsKPI 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
Pageskpi_daily_pages (rollup), kpi_events for the drill-downsortable, 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
Eventskpi_daily_events (rollup), kpi_events for distinct users and the detailevery 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_eventsscroll 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)
Productskpi_daily_products, site_products, kpi_eventsviews, 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
Searchkpi_eventstop 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
Retentionsite_orders, kpi_sessionscustomers 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
Funnelskpi_daily_funnels, kpi_eventsstylised 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 only http(s), mailto, relative and anchors, images only same-site relative paths (no external image loads); node resources/js/utils/markdown.test.mjs runs the XSS payload checks

Routing: all BI Agent endpoints are prefixed /nova-vendor/nova-ai-report/bi-agent/ and protected by Nova + Authorize middleware.

MethodPathDescription
POSTchatStream a response (SSE)
GETconfigAvailable models, defaults, KPI table presence
GETcreditsOpenRouter credit balance
GETusagePer-day usage stats
GET/POSTconversationsList / create
GET/PATCH/DELETEconversations/{id}Show / update / delete
GET/POSTpromptsList / create prompts
PATCH/DELETEprompts/{id}Update / delete prompt
POSTexportGenerate 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 — html2canvas captures 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

VersionDateNotes
1.8.02026-11-11Securitate (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.02026-11-06Rapoarte î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.02026-11-06KPI 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.12026-10-19Compatibilitate Laravel 11, 12 și 13 (laravel/framework ^11.0\|^12.0\|^13.0); PHP minim 8.2
1.5.02026-10-15Briefuri 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.132026-10-13Kimi (latest) grupat sub furnizorul Moonshot, alături de Kimi K2
1.4.122026-10-13Modele: aliasuri „latest” Gemini Flash, Gemini Pro și Kimi (Moonshot AI)
1.4.112026-10-13Modele: aliasuri OpenRouter „latest” pentru OpenAI (Astra, Sol, Terra, Mini), Anthropic (Sonnet, Opus, Fable) și xAI (Grok); implicit Sonnet/Opus latest
1.4.102026-10-12Security: 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.82026-05-19Fix 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.12026-05-02Fix 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.02026-04-30Migrations bundled in package; AiReportPromptSeeder (30 e-commerce reports); KPI tabs auto-hidden; Romanian terminology; operational tables priority; table overflow fix
1.2.02026-04-30Chat export to HTML (html2canvas); nudge/retry chips; transitional message styling
1.1.02026-04-29Saved Prompts (global library + modal picker + management tab)
1.0.02026-04-29Initial release — BI Agent chat, KPI dashboards, model picker, usage tracking