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

Minimum .env:

OPENROUTER_API_KEY=sk-or-...

Database

Tables

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:

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.

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.

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