concept24/nova-ai-report

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

v1.4.5 2026-05-05 04:09 UTC

Requires

• php: >=8.1
• laravel/framework: ^12.0
• laravel/nova: ^4.12|^5.0

MIT

• analytics
• nova
• tool
• laravel
• e-commerce
• reports
• kpi

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.1
• Laravel 12
• 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-sonnet-4.6
models.primary	NOVA_AI_REPORT_MODEL_PRIMARY	anthropic/claude-sonnet-4.6
models.fast	NOVA_AI_REPORT_MODEL_FAST	google/gemini-3-flash-preview
models.reasoning	NOVA_AI_REPORT_MODEL_REASONING	anthropic/claude-opus-4.7
max_tool_iterations	NOVA_AI_REPORT_MAX_TOOL_ITERATIONS	15
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 powered by pre-aggregated kpi_* tables. Tabs are hidden automatically if kpi_daily_sales does not exist in the database.

Tab	Data source
Overview	Cross-table KPI summary
Sales	kpi_daily_sales, site_orders
Traffic	kpi_daily_traffic, kpi_sessions
UX	kpi_daily_ux, kpi_webvitals
Products	kpi_daily_products, site_products
Funnels	kpi_daily_funnels, kpi_events

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, Gemini Pro, Claude Sonnet, Claude Opus, Grok
• 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

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 — 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
  Services/
    BiAgentOrchestrator.php      — tool-call loop
    ChatExportService.php        — HTML export generation
    KpiSchemaProvider.php        — system prompt + schema introspection
    KpiQuerySanitizer.php        — SQL safety (SELECT/WITH only, 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 / FunnelsTab.vue
    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.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