AI Reporting Engine

How it works

7-Step Query Pipeline

Every prompt passes through the same pipeline. The engine produces a DSL only — execution is delegated to dynamic-hybrid-reporting-engine, fed by dual-layer-reporting-engine.

01PromptNormalizer

Trim, lowercase, Arabic letters, tashkeel & punctuation → fingerprint

02Cache Lookup

Hit → load stored DSL, skip regex + OpenAI

03RegexParser

Token-free match → IntermediateQuery

04OpenAiParser

On regex miss → structured JSON → IntermediateQuery

05DslBuilder

The only place that builds DSL — validate & map

06Cache Store

Persist intent + DSL (never rows)

07ReportEngine.run

Execute DSL — the unchanged reporting engine

Unified Query Object

One Shape — Regex or AI, the System Can't Tell

Both parsers return the exact same IntermediateQuery. Only the parser knows its source; the DSL builder and the rest of the app stay source-agnostic.

⚙️ RegexParser output

{
  "module": "students",
  "operation": "list",
  "filters": [
    { "field":"class_id", "operator":"=", "value":1 }
  ],
  "projection": ["first_name_ar","status"],
  "limit": 20,
  "_source": "regex"
}

🧠 OpenAiParser output

{
  "module": "books",
  "operation": "list",
  "filters": [
    { "field":"title_ar", "operator":"like", "value":"مقدمة" }
  ],
  "projection": ["title_ar","author"],
  "limit": 20,
  "_source": "openai"
}

Two Engines, One Contract

Regex First, OpenAI on Miss

The parse method is switchable: auto (regex → OpenAI), regex (no tokens), or openai. Every collaborator sits behind an interface.

⚙️

RegexParser

Deterministic and token-free. Matches editable MongoDB mappings and column concepts. Resolves "students in class 1-A" to a class_id filter via a pluggable EntityResolver.

🧠

OpenAiParser

Runs only when regex can't match. Returns strict JSON — never DSL, never raw SQL. Tracks latency and token usage for the execution log.

🔑

Fingerprint Cache

Equivalent prompts (spacing, tashkeel, alef variants) share one fingerprint, so a repeated question skips parsing entirely and costs zero tokens.

Developer Experience

Code Examples

Inject the pipeline, get a DSL, hand it to the reporting engine.

use Mostafax\AiReportingEngine\ReportQueryPipeline;
use Mostafax\ReportingEngine\Core\Engine\ReportEngine;

public function search(Request $request, ReportQueryPipeline $pipeline, ReportEngine $engine)
{
    $result = $pipeline->process($request->string('question'));
    // ['source'=>'regex|openai|cache', 'collection'=>…, 'query'=>…, 'dsl'=>…, 'cached'=>bool]

    $rows = $engine->run($result['dsl']);   // execute via the reporting engine

    return response()->json(['data' => $rows->data, 'source' => $result['source']]);
}

// Enable class-name → class_id lookups (host-specific)
$this->app->bind(
    EntityResolverInterface::class,
    MyClassResolver::class,
);

// Swap the AI config source (e.g. DB-backed settings)
$this->app->singleton(
    AiConfigInterface::class,
    SystemSettingAiConfig::class,
);

// config/ai-reporting.php
return [
    'enabled'      => true,
    'parse_method' => 'auto',   // auto | regex | openai
    'openai' => [
        'api_key'       => env('OPENAI_API_KEY'),
        'model'         => 'gpt-4o-mini',
        'schema_prompt' => '…your collections + columns…',
    ],
    'storage' => [ 'connection' => 'mongodb' ],
];

Features

Built for Reuse — Nothing Hard-wired

🧹

Arabic Normalization

Alef/teh-marbuta unify, tashkeel & punctuation stripped.

🔑

Fingerprint Cache

SHA-256 of the normalized prompt — zero tokens on repeats.

🎯

Unified Query

Regex & AI return the same IntermediateQuery.

🏗️

Central DSL Builder

The single place that emits an executable DSL.

🔌

SOLID + DI

Every collaborator is a swappable interface.

🍃

MongoDB Store

Editable mappings, concepts & prompt cache.

🧩

Entity Resolver

Map names ("class 1-A") to ids for filtering.

📊

Execution Logging

Parser, cache hit, ms, tokens, generated DSL.

Installation

Up and Running in Minutes

Both reporting packages are hard requirements and are pulled in automatically.

$ composer require mostafax/ai-reporting-engine
$ php artisan vendor:publish --tag=ai-reporting-config

Requires

mostafax/dynamic-hybrid-reporting-engine — executes the DSL.
mostafax/dual-layer-reporting-engine — replicates data for reporting.

Parse Method

auto — regex first, OpenAI on miss (recommended).
regex — local only, no tokens.
openai — AI only.