Overview

BlunxAI turns your database into an agentic collaborator: your users ask questions in natural language and receive answers, charts, tables and automatic insights - directly inside your application.

The principle

BlunxAI is not an external platform to which you would export your data: it is an SDK that you embed in your own infrastructure. SQL is executed locally, in read-only mode, and the multi-agent system is driven by the Blunx server (the cloud endpoint /api/v1/*).

Architecture

Key takeaways

• Strictly read-only: only SELECT / WITH statements are executed, guarded at several levels (see Security).
• Backend-agnostic: the Web SDK only expects a REST contract /api/blunx/*. The Laravel and Node.js packages implement it today; Django, Go and Spring Boot SDKs will follow without any frontend change.
• One server, several keys: the backend SDK authenticates to the Blunx server with an application key (X-Blunx-Key) and an LLM key (X-Blunx-LLM-Key).
• Your database, your rules: MySQL, MariaDB, PostgreSQL, SQLite and SQL Server are supported; you control access by role (RBAC).

Quick start

Install Blunx in your application in ~5 minutes. Choose your backend (Laravel or Node.js): the outline is identical, only the SDK changes. Each step is minimal - the details are in the guides.

What you are going to do: 1 · get your keys → 2 · install the SDK → 3 · configure the .env → 4 · connect Blunx and exclude sensitive tables → 5 · generate your database schema → 6 · integrate the interface (Web SDK) into your pages. Once in place, Blunx turns your users' questions into SQL in read-only mode against your database: it never modifies your data.

Requirements

1 · Get your keys

Gather these 4 pieces of information - you will need them at step 3:

composer require blunx/ai
php artisan vendor:publish --tag=blunx-config

BLUNX_API_KEY=blunx_app_live_xxxxxxxxxxxx
BLUNX_LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
BLUNX_LLM_ENDPOINT=https://api.openai.com/v1
BLUNX_LLM_MODEL=gpt-4o

// Already excluded by default: migrations, failed_jobs, cache, jobs, sessions,
// password_reset_tokens, personal_access_tokens... + all blunx_* tables
'excluded_tables' => [
    'admin_logs', 'notifications', 'settings', 'audit_trail',   // ▶ your tables
],

php artisan blunx:init    # scans the database → storage/app/blunx_schema.json
php artisan blunx:setup   # locks the schema + creates the 8 tables

public function getUserRoleName(): ?string
{
    return $this->role->name ?? null;
}

<div id="blunx" style="height:100vh;"></div>
<script src="https://cdn.jsdelivr.net/npm/@blunx/web-sdk/dist/blunx-loader.min.js"
        data-container="#blunx"
        data-view="auto"></script>

npm install blunx-ai

BLUNX_API_KEY=blunx_app_live_xxxxxxxxxxxx
BLUNX_LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
BLUNX_LLM_ENDPOINT=https://api.openai.com/v1
BLUNX_LLM_MODEL=gpt-4o
# Your database (ADAPT) - mysql://user:password@host:port/database
BLUNX_DB_URL=mysql://root:secret@127.0.0.1:3306/my_database

const { Blunx, blunxExpress } = require('blunx-ai');   // 1. import

// 2. Blunx runtime - keys (BLUNX_API_KEY, BLUNX_LLM_*) and database (BLUNX_DB_URL)
//    read from the .env. The 2 hooks below are MANDATORY:
const blunx = Blunx.init({
  getUserRole: (userId) => null,   // TODO: return the role label (e.g. 'admin')
  getUser: (userId) => null,       // TODO: return { name, email } or null
});

// 3. Mount the Blunx router AFTER your authentication middleware
//    (the latter must have populated req.user beforehand)
app.use('/api/blunx', blunxExpress(blunx));

getUserRole: (userId) => users[userId]?.role ?? null,
getUser: (userId) => {
  const u = users[userId];
  return u ? { name: u.name, email: u.email } : null;
},

const express = require('express');                   // HTTP framework
const { Blunx, blunxExpress } = require('blunx-ai');   // Blunx SDK

const app = express();
app.use(express.json());   // parses the JSON body

// ── Demo users (ADAPT: come from your users table) ──
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'   },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'sales_rep' },
};

// ── Authentication (ADAPT: Passport, JWT, session...) ──
// Blunx returns 401 if req.user is missing: your auth middleware
// must run BEFORE the Blunx router and populate req.user.
app.use((req, res, next) => {
  req.user = USERS[1];   // demo: user 1 is logged in
  next();
});

// ── Blunx runtime (keys + database read from the .env) ──
const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// ── Blunx router mounted AFTER auth ──
app.use('/api/blunx', blunxExpress(blunx));

// ── Startup ──
app.listen(3000, () => console.log('Blunx ready on http://localhost:3000'));

cp node_modules/blunx-ai/config/blunx.config.ts ./config/blunx.config.ts
cp node_modules/blunx-ai/config/blunx-access.config.ts ./config/blunx-access.config.ts

import blunxConfig from './config/blunx.config';            // your edited copy
import blunxAccessConfig from './config/blunx-access.config'; // your RBAC rules

const blunx = Blunx.init({
  ...blunxConfig,             // serverUrl, apiKey, llm, currency, locale...
  access: blunxAccessConfig,  // RBAC rules
  // hooks identical to those in Case A / B above (USERS):
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

export default {
  // Internal blunx_* tables are already ignored by default.
  // ▶ Add your technical / sensitive tables that must not be scanned:
  excludedTables: ['migrations', 'sessions', 'log_errors', 'admin_logs', 'notifications'],
};

npx blunx-ai init    # scans the database → storage/app/blunx_schema.json
npx blunx-ai setup   # locks the schema + creates the 8 tables

<div id="blunx" style="height:100vh;"></div>
<script src="https://cdn.jsdelivr.net/npm/@blunx/web-sdk/dist/blunx-loader.min.js"
        data-container="#blunx"
        data-view="auto"></script>

Check that everything works

Log in with a user of your application and open the page. Ask a question (e.g. "How many customers do we have in total?"): the cockpit displays the pipeline then the result.

Compatibility

Supported versions and environments, per integration layer. Backend SDKs: Laravel and Node.js are available, the others will follow.

Databases

Blunx works with your application's connection and runs SQL in read-only mode. The following databases are supported by the Laravel SDK and by the Blunx server:

Backend (server SDK)

Frontend (Web SDK @blunx/web-sdk)

LLM providers

The openai driver is an OpenAI-compatible adapter: it works with almost every provider, proprietary AND open-source. See LLM providers for details.

Browsers & environments

Laravel backend

The blunx/ai package serves the /api/blunx/* contract expected by the Web SDK, runs SQL in read-only mode against your database and proxies to the Blunx server. Requirements: Laravel 9 to 12 (tested on 12), PHP 8.1+.

Installation

composer require blunx/ai
php artisan vendor:publish --tag=blunx-config

• Provider in auto-discovery - no manual declaration.
• No migration to publish: the 8 Blunx tables are created by blunx:setup.

Configuration

Two files published into config/: blunx.php (read from your BLUNX_* variables) and blunx_access.php (RBAC rules). The full variable reference is in Configuration.

public function getUserRoleName(): ?string
{
    return $this->role->name ?? null;
}

Artisan commands

Workflow: blunx:init → (optional) blunx:edit → blunx:setup. Re-run blunx:edit after every change to your database.

Tables created

All of them have an auto-increment id + a unique uuid (routes are bound by uuid):

Authentication & routes

All /api/blunx/* routes are in the blunx middleware group = session + auth (logged-in user required, no CSRF) + throttle:60,1. Nothing to configure: an unauthenticated request is blocked by the framework (401/redirect).

Queue & insights

• GenerateWidgetInsightJob: ShouldQueue, tries=5, timeout=200 - runs the widget, generates the PDF report and the email.
• BlunxInsightMail: email colour-coded by severity, PDF attached.
• Scheduling: hourly for "due" settings; a new setting runs immediately.
• Failure after retries (e.g. server call in error): the job does not advance to the next slot - it retries in 30 min (next_run_at = now + 30 min, last_run_at unchanged until the job succeeds).
• Locally: php artisan queue:work --once (or QUEUE_CONNECTION=sync in dev).

Node.js backend

The blunx-ai package serves the /api/blunx/* contract expected by the Web SDK, runs read-only SQL against your database and proxies to the Blunx server. Requirements: Node.js 18+, framework-agnostic (Express, Fastify, Koa, NestJS or native HTTP).

Installation

npm install blunx-ai

• The .env file is loaded automatically (dotenv) - no config publishing required.
• No migration to publish: the 8 Blunx tables are created by blunx-ai setup.

Initialization

Create the Blunx runtime once, with your authentication hooks. Configuration precedence: Blunx.init() option > BLUNX_* environment variable > default (see Configuration).

Your database connection can be provided in 3 ways (from the simplest to the most integrated):

const { Blunx } = require('blunx-ai');

// Keys (BLUNX_API_KEY, BLUNX_LLM_*) and database (BLUNX_DB_URL) are read from .env.
// Sample user resolution (ADAPT THIS: load from your own database):
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'    },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'sales_rep' },
};

const blunx = Blunx.init({
  // Resolves the user role (RBAC) - equivalent to Laravel's getUserRoleName()
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  // Resolves {name, email} for /api/blunx/user - equivalent to Laravel's Auth::user()
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

Option (advanced) - publish and load the config files

You do not need this to get started: the .env file is enough. This option does not replace the initialization above - it only changes the source of the configuration. Use it if you want to version your settings and RBAC rules in TypeScript files rather than in the .env file. Copy the 2 templates (no dependency), edit them, then load them in Blunx.init():

cp node_modules/blunx-ai/config/blunx.config.ts ./config/blunx.config.ts
cp node_modules/blunx-ai/config/blunx-access.config.ts ./config/blunx-access.config.ts

import blunxConfig from './config/blunx.config';            // your edited copy
import blunxAccessConfig from './config/blunx-access.config'; // your RBAC rules

const blunx = Blunx.init({
  ...blunxConfig,             // serverUrl, apiKey, llm, currency, locale...
  access: blunxAccessConfig,  // RBAC rules
  // same hooks as above (USERS):
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

The database is passed through BLUNX_DB_URL (.env) or the database option. RBAC rules are detailed in Configuration.

Commands (CLI blunx-ai)

Workflow: blunx-ai init → (optional) blunx-ai edit → blunx-ai setup. The CLI builds its own connection from the .env file (BLUNX_DB_URL or BLUNX_DB_*) - run it from the root of your project.

Created tables

Identical to the Laravel package: blunx_conversations, blunx_messages, blunx_feedbacks, blunx_dashboards, blunx_dashboard_widgets, blunx_insights, blunx_widget_insight_settings, blunx_cache (all with a unique id + uuid).

Authentication & routes

The package protects the routes itself: with no authenticated user (req.user / ctx.state.user missing), it returns 401 {"message":"Unauthenticated."} - equivalent to the auth middleware of Laravel's blunx group. No requireAuth guard to add.

const express = require('express');
const { Blunx, blunxExpress } = require('blunx-ai');

const app = express();
app.use(express.json());

// Sample users (ADAPT THIS: load from your own database)
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'    },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'sales_rep' },
};

// 1. Authentication: your auth middleware (Passport, JWT, session...)
//    populates req.user. Demo example:
app.use((req, res, next) => {
  req.user = USERS[1];
  next();
});

const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// 2. Blunx mounted AFTER: it checks req.user and returns 401 when it is missing
app.use('/api/blunx', blunxExpress(blunx));

app.listen(3000);

Blunx reads req.user.id (user_id filtering), req.user.name/email (the /user endpoint) and optionally req.user.getUserRoleName() (otherwise your getUserRole hook is called). Other adapters: blunxFastify, blunxKoa, createBlunxNestController, blunxNodeHttp.

Insight scheduling

• Scheduler (node-cron): every hour, it finds the "due" settings and runs GenerateWidgetInsightJob. Enabled by default (enableScheduler: true), it can be disabled through Blunx.init({ enableScheduler: false }).
• npx blunx-ai run-insights: immediate manual run.
• Failure after retries (e.g. a failing server call): the job does not move to the next slot - it retries in 30 min (next_run_at = now + 30 min, last_run_at unchanged until the job succeeds).
• sendInsightMail (nodemailer): email colored by severity, PDF as an attachment (generated by InsightPdfGenerator - 100% JS rendering, no browser).

Complete examples per framework

Each example is a complete, copy-pastable file: sample users, authentication, runtime and startup. Replace the blocks marked ADAPT THIS (database, auth, roles) with your real data. Keys + database in the .env file.

const express = require('express');                   // HTTP framework
const { Blunx, blunxExpress } = require('blunx-ai');   // Blunx SDK

const app = express();
app.use(express.json());   // parses the JSON body

// -- Sample users (ADAPT THIS: load from your users table) --
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'    },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'sales_rep' },
};

// -- Authentication (ADAPT THIS: Passport, JWT, session...) --
app.use((req, res, next) => {
  req.user = USERS[1];   // demo: user 1 is signed in
  next();
});

// -- Blunx runtime (keys + database from .env) --
const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// -- Blunx router mounted AFTER authentication --
app.use('/api/blunx', blunxExpress(blunx));

app.listen(3000, () => console.log('Blunx ready on http://localhost:3000'));

const fastify = require('fastify');
const { Blunx, blunxFastify } = require('blunx-ai');

const app = fastify();

// Sample users (ADAPT THIS)
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'    },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'sales_rep' },
};

// Authentication (ADAPT THIS): populates req.user before the Blunx router
app.addHook('onRequest', (req, reply, done) => {
  req.user = USERS[1];
  done();
});

// Blunx runtime (keys + database from .env)
const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// Mounting the Blunx router
blunxFastify(app, blunx);

app.listen({ port: 3000 }).then(() => console.log('Blunx ready on http://localhost:3000'));

const Koa = require('koa');
const bodyParser = require('koa-bodyparser');   // required: parses the JSON body
const { Blunx, blunxKoa } = require('blunx-ai');

const app = new Koa();
app.use(bodyParser());

// Sample users (ADAPT THIS)
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'    },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'sales_rep' },
};

// Authentication (ADAPT THIS): populates ctx.state.user before the Blunx router
app.use(async (ctx, next) => {
  ctx.state.user = USERS[1];
  await next();
});

// Blunx runtime (keys + database from .env)
const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// Mounting the Blunx router
app.use(blunxKoa(blunx));

app.listen(3000, () => console.log('Blunx ready on http://localhost:3000'));

import { Module } from '@nestjs/common';
import { Blunx, createBlunxNestController } from 'blunx-ai';

// Sample users (ADAPT THIS)
const USERS: Record<number, any> = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'    },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'sales_rep' },
};

// Blunx runtime (keys + database from .env)
const blunx = Blunx.init({
  getUserRole: (userId: any) => USERS[userId]?.role ?? null,
  getUser: (userId: any) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// Blunx controller (your Nest auth guard must populate req.user - ADAPT THIS)
const BlunxController = createBlunxNestController(blunx);

@Module({ controllers: [BlunxController] })
export class BlunxModule {}

const http = require('http');
const { Blunx, blunxNodeHttp } = require('blunx-ai');

// Sample users (ADAPT THIS)
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'    },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'sales_rep' },
};

// Blunx runtime (keys + database from .env)
const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

http.createServer((req, res) => {
  // Authentication (ADAPT THIS): populates req.user before the Blunx router
  req.user = USERS[1];

  if (blunxNodeHttp(blunx, req, res)) return;   // request handled by Blunx
  res.writeHead(404).end();
}).listen(3000, () => console.log('Blunx ready on http://localhost:3000'));

Web SDK

The Web SDK (@blunx/web-sdk) is a self-contained, embeddable front-end application: chat + canvas cockpit, dashboards and insights. It mounts into a plain DOM container. Integration is identical whatever your backend (Laravel, Node.js...).

Distribution formats

Integration per framework

<div id="blunx" style="height:100vh;"></div>
<script src="https://cdn.jsdelivr.net/npm/@blunx/web-sdk/dist/blunx-loader.min.js"
        data-container="#blunx"
        data-view="auto"></script>

<div id="blunx" style="height:100vh;"></div>
<script src="https://cdn.jsdelivr.net/npm/@blunx/web-sdk/dist/blunx.min.js"></script>
<script>
  Blunx.init({ container: '#blunx', view: 'auto' })
    .then(function (info) { console.log('[Blunx] ready', info); })
    .catch(function (err) { console.error('[Blunx] failed', err); });
</script>

npm install @blunx/web-sdk

import { useEffect } from 'react';
import { init, destroy, navigate } from '@blunx/web-sdk';

export default function App() {
    useEffect(() => {
        let mounted = true;

        init({
            container: '#blunx',
            apiBaseUrl: '', // cross-origin - leave empty for same origin
            view: 'auto',
            onReady: (info) => console.log('[React] Blunx ready', info),
            onError: (err) => console.error('[React] Blunx error', err),
        })
            .then((info) => { if (mounted) console.log('[React] mounted', info); })
            .catch((err) => console.error('[React] init failed', err));

        return () => { mounted = false; destroy(); }; // unmount (StrictMode-safe)
    }, []);

    return (
        <div className="host">
            <header className="host-top">
                <strong>React host</strong>
                <span>SDK mounted in <code>#blunx</code></span>
            </header>
            <div id="blunx" className="blunx-zone" />
        </div>
    );
}

'use client';

import { useEffect, useRef } from 'react';

export default function Home() {
    const apiRef = useRef(null);

    useEffect(() => {
        let mounted = true;

        import('@blunx/web-sdk')
            .then(({ init, destroy, navigate }) => {
                apiRef.current = { destroy, navigate };
                return init({
                    container: '#blunx',
                    apiBaseUrl: '', // cross-origin - leave empty for same origin
                    view: 'auto',
                    onReady: (info) => console.log('[Next] Blunx ready', info),
                    onError: (err) => console.error('[Next] Blunx error', err),
                });
            })
            .then((info) => { if (mounted) console.log('[Next] mounted', info); })
            .catch((err) => console.error('[Next] init failed', err));

        return () => { mounted = false; apiRef.current?.destroy?.(); };
    }, []);

    return (
        <main className="host">
            <header className="host-top">
                <strong>Next.js host</strong>
                <span>SDK imported dynamically (SSR-safe)</span>
            </header>
            <div id="blunx" className="blunx-zone" />
        </main>
    );
}

npm install @blunx/web-sdk

<script setup>
import { onMounted, onUnmounted } from 'vue';
import { init, destroy, navigate } from '@blunx/web-sdk';

onMounted(async () => {
    try {
        const info = await init({
            container: '#blunx',
            apiBaseUrl: '', // cross-origin - leave empty for same origin
            view: 'auto',
            onReady: (i) => console.log('[Vue] Blunx ready', i),
            onError: (e) => console.error('[Vue] Blunx error', e),
        });
        console.log('[Vue] mounted', info);
    } catch (e) {
        console.error('[Vue] init failed', e);
    }
});

onUnmounted(() => {
    destroy(); // unmounts the SDK when the component is removed
});
</script>

<template>
    <div class="host">
        <header class="host-top">
            <strong>Vue 3 host</strong>
            <span>SDK mounted in <code>#blunx</code></span>
        </header>
        <div id="blunx" class="blunx-zone" />
    </div>
</template>

import { Component, OnInit, OnDestroy } from '@angular/core';
import { init, destroy, navigate } from '@blunx/web-sdk';

@Component({
    selector: 'app-root',
    standalone: true,
    template: `
        <div class="host">
            <header class="host-top">
                <strong>Angular host</strong>
                <span>SDK mounted in <code>#blunx</code></span>
            </header>
            <div id="blunx" class="blunx-zone"></div>
        </div>
    `,
})
export class AppComponent implements OnInit, OnDestroy {
    async ngOnInit(): Promise<void> {
        try {
            const info = await init({
                container: '#blunx',
                apiBaseUrl: '', // cross-origin - leave empty for same origin
                view: 'auto',
                onReady: (i) => console.log('[Angular] Blunx ready', i),
                onError: (e) => console.error('[Angular] Blunx error', e),
            });
            console.log('[Angular] mounted', info);
        } catch (e) {
            console.error('[Angular] init failed', e);
        }
    }

    ngOnDestroy(): void {
        destroy(); // unmounts the SDK when the component is destroyed
    }

}

<script>
    import { onMount, onDestroy } from 'svelte';
    import { init, destroy, navigate } from '@blunx/web-sdk';

    onMount(async () => {
        try {
            const info = await init({
                container: '#blunx',
                apiBaseUrl: '', // cross-origin - leave empty for same origin
                view: 'auto',
                onReady: (i) => console.log('[Svelte] Blunx ready', i),
                onError: (e) => console.error('[Svelte] Blunx error', e),
            });
            console.log('[Svelte] mounted', info);
        } catch (e) {
            console.error('[Svelte] init failed', e);
        }
    });

    onDestroy(() => {
        destroy(); // unmounts the SDK when the component is destroyed
    });
</script>

<div class="host">
    <header class="host-top">
        <strong>Svelte host</strong>
        <span>SDK mounted in <code>#blunx</code></span>
    </header>
    <div id="blunx" class="blunx-zone"></div>
</div>

Public API & options

import { init, destroy, navigate, version } from '@blunx/web-sdk';

init(options)  // → Promise<{ view: 'cockpit'|'dashboard', version }>
destroy()      // unmounts and cleans up the hashchange listener + the container content
navigate(path) // internal navigation, e.g. navigate('/dashboard/abc-123') → '#/dashboard/abc-123'
version        // string, e.g. "0.1.0"

With a script tag, options are passed as data-* attributes: data-container, data-api-base-url, data-view, data-dashboard-uuid.

Pitfalls & best practices

Configuration

This page is the full reference: every environment variable, every Blunx.init() option and the RBAC access rules. In most cases, the .env is enough.

The 3 ways to configure

Environment variables

Alternative column: blunx.* key (Laravel) / init() option (Node).

The tables excluded from the scan (excluded_tables in Laravel, excludedTables in Node) and the RBAC rules (access) have no environment variable: they are passed by option/file (see the sections below).

Blunx.init() - every option (Node.js)

Complete reference of what you can pass to Blunx.init(). Priority: option > environment variable > default. The TypeScript template config/blunx.config.ts (exported, dependency-free) uses these keys in camelCase; snake_case keys (server_url, api_key, db_url...) are also accepted (mirroring config/blunx.php).

Loading the config files (Node.js)

Complete example: we publish config/blunx.config.ts + config/blunx-access.config.ts (TypeScript templates, no dependency), load them, and add the database + the hooks:

import blunxConfig from './config/blunx.config';            // your edited copy
import blunxAccessConfig from './config/blunx-access.config'; // your RBAC rules

const blunx = Blunx.init({
  ...blunxConfig,          // serverUrl, apiKey, llm, currency, locale...
  access: blunxAccessConfig,  // RBAC rules
  // Database: via BLUNX_DB_URL in the .env (recommended), or:
  // database: { client: 'mysql2', connection: { host, user, password, database } },
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

RBAC access rules (access)

NEGATIVE approach: you define what the user is NOT allowed to see. In Laravel: config/blunx_access.php. In Node: the access option of Blunx.init() (file config/blunx-access.config.ts). No environment variable.

Three levels of restriction per role:

Complete example (file config/blunx-access.config.ts):

export default {
  "sales_rep": {
    "forbidden_tables": ["salaries", "accounting"],
    "forbidden_columns": {
      "users": ["salary", "ssn", "full_address"],
      "*": ["password", "api_token"]
    },
    "row_level": {
      "orders":   { "column": "user_id", "value": "USER_ID" },
      "products": { "column": "vendor_id", "value": "USER_ID" }
    }
  },
  "admin":   { "forbidden_tables": [], "forbidden_columns": [], "row_level": {} },
  "default": { "forbidden_tables": ["users"], "forbidden_columns": {}, "row_level": {} },
  "enabled": true
}

• USER_ID: placeholder replaced by the logged-in user's ID.
• The SDK merges default + the role's rules (recursive merge, like array_replace_recursive).
• If no role can be resolved → null → SSE error Access rules not resolved.
• enabled: turns the whole permission system on or off.

Tables excluded from the scan (excluded_tables / excludedTables)

When the schema is generated (blunx:init / npx blunx-ai init), Blunx scans all the tables in your database and makes them queryable by the assistant. List here the technical, sensitive or useless tables that must never appear in the schema. No environment variable: the list is declared by file/option.

'excluded_tables' => [
    // Already excluded by default: migrations, failed_jobs, cache, jobs, sessions,
    // password_reset_tokens, personal_access_tokens... + the internal blunx_* tables
    'admin_logs', 'notifications', 'settings', 'audit_trail',   // ▶ your tables
],

export default {
  // ...
  // Internal blunx_* tables are already ignored by default.
  // ▶ Add your technical / sensitive tables that must not be scanned:
  excludedTables: ['migrations', 'sessions', 'log_errors', 'admin_logs', 'notifications'],
};

A complete .env ready to copy

# --- Blunx server ---
BLUNX_SERVER_URL=https://blunxai.com
# Timeout (s) for each request to the Hub - 600 (10 min) by default; 0 = none
BLUNX_REQUEST_TIMEOUT=600
BLUNX_API_KEY=blunx_app_live_xxxxxxxxxxxx

# --- LLM provider (OpenAI in this example) ---
BLUNX_LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
BLUNX_LLM_DRIVER=openai
BLUNX_LLM_ENDPOINT=https://api.openai.com/v1
BLUNX_LLM_MODEL=gpt-4o
BLUNX_LLM_SUPPORTS_JSON_FORMAT=true

# --- Database ---
BLUNX_DB_CONNECTION=mysql
# BLUNX_DB_URL=postgres://user:pass@host:5432/db?sslmode=require   # alternative: connection URL (DSN)
# BLUNX_READONLY_DB_USERNAME=blunx_readonly   # optional (see connection modes)
# BLUNX_READONLY_DB_PASSWORD=secret
# BLUNX_PGSQL_SCHEMA=public                    # PostgreSQL only

# --- Display & language ---
BLUNX_CURRENCY_CODE=EUR
BLUNX_CURRENCY_SYMBOL=€
BLUNX_CURRENCY_LOCALE=en_US
BLUNX_LOCALE=en

The 3 database connection modes

Blunx runs SQL against your database. Three complementary notions - do not confuse them:

API contract

Two families of endpoints: the Web SDK only knows the local endpoints /api/blunx/* served by your backend SDK; the latter proxies to the Blunx server /api/v1/*.

Local endpoints (/api/blunx/*)

Session + auth, no CSRF, throttle 60:1. Responses wrapped in { "data": ... }, except /user (direct object).

Blunx server endpoints (/api/v1/*)

Middlewares: ValidateBlunxKey (X-Blunx-Key) then RequireLLMConfig (X-Blunx-LLM-Key + the llm block in the body).

Common headers

X-Blunx-Key: blunx_app_live_xxxxxxx      # application key (required)
X-Blunx-LLM-Key: sk-xxxxxxxxxxxxxxxx     # LLM provider key (required)
Content-Type: application/json
Accept: text/event-stream | application/json

Base payload

Every call to the Blunx server carries the database connection and the LLM configuration. Keys travel in the headers, never in the body (no leakage into logs).

{
  "db_connection": "mysql",
  "locale": "fr",
  "currency": { "code": "XOF", "symbol": "FCFA", "locale": "fr_FR" },
  "llm": {
    "driver": "openai",
    "endpoint": "https://api.openai.com/v1",
    "model": "gpt-4o",
    "supports_json_format": true
  }
}

Chat - POST /api/v1/chat/queries

Request:

{
  "question": "What is the revenue per region?",
  "conversation_history": [ { "role": "user", "content": "..." } ],
  "access_rules": { "forbidden_tables": [], "forbidden_columns": [], "row_level": [] },
  "schema": "... full schema as a JSON string (or schema_id) ...",
  "schema_id": "optional-uuid",
  "db_connection": "mysql",
  "locale": "en",
  "currency": { "code": "USD", "symbol": "$", "locale": "en_US" },
  "llm": { "driver": "openai", "endpoint": "...", "model": "...", "supports_json_format": true }
}

SSE response - result event:

{
  "needs_data": true,
  "needs_clarification": false,
  "normalized_question": "...",
  "intent": "...",
  "queries": [ { "sql": "SELECT ...", "ui_hint": "chart", "chart_type": "bar" } ],
  "warnings": [],
  "filtered_schema_id": "uuid"
}

Terminal cases: needs_clarification (+ clarification_question), needs_data=false, access_denied (+ message, forbidden_info).

Chat - validate & synthesize

Validate: {normalized_question, intent, execution_results, filtered_schema_id, access_rules, locale, db_connection, llm} → {queries[], warnings[]} (corrected SQL).

Synthesize: {normalized_question, execution_results, conversation_history, needs_data, locale, currency, llm} → structured answer:

{
  "title": "Revenue per region",
  "layout": [
    { "type": "paragraph", "content": "... Bootstrap 5 HTML ..." },
    { "type": "chart", "chart_type": "bar", "title": "...", "label_column": "...",
      "data_columns": ["..."], "comment": "...", "sql_query": "..." },
    { "type": "table", "title": "...", "comment": "...", "sql_query": "..." }
  ],
  "Resume": "... markdown summary ..."
}

If needs_data=false: { "Resume": "...", "is_conversational": true }.

Insights, schema & references

• Analyze : {widget_title, sql_query, current_meta, previous_meta?, metric_weights?, locale, currency, llm} → {type, severity, message, meta}.
• Report : {insight_result, current_meta, previous_meta?, last_insight?, widget_title, dashboard_name, report_frequency, locale, currency, llm} → {html}.
• Schema enrich: {columns, locale, llm} → {columns} with descriptions.
• Reference generate: {widget_sql, widget_title?, numeric_columns[], access_rules?, db_connection, locale, llm} → {queries}.

SSE stream - events

event: step
data: {"step":1,"status":"running","duration":1}

event: result
data: { ...result... }

event: done
data: {"result":{ "title":"...", "Resume":"...", "layout":[...] }, "message_uuid":"..."}

event: error
data: {"message":"..."}

Security & access

Blunx applies defense in depth across several layers to guarantee that your data is never modified or exposed beyond what you authorize.

1. Strictly read-only (SqlGuard)

Every SQL query is validated locally before execution. The rules are multiple:

• The query must start with SELECT or WITH (CTE).
• Forbidden dangerous keywords: INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, GRANT, REVOKE, EXEC, VACUUM, LOCK, COPY, etc.
• Forbidden dangerous functions: pg_sleep, pg_read_file, lo_import, dblink, pg_execute_server_program, set_config, etc.
• SELECT ... INTO is forbidden.
• A sanitize() step strips string literals and comments before analysis (avoiding false positives on values).

invalid statement type: INSERT (only SELECT allowed)
forbidden keyword found: DROP
forbidden function call found: pg_sleep
SELECT ... INTO is forbidden ...

Even if a query were tampered with between generation and execution, the execution agent (DataExecutorAgent) re-validates it and skips any non-SELECT query.

2. Dedicated read-only database connection

This is the main security lock. If BLUNX_READONLY_DB_USERNAME is set, the package creates a blunx_readonly connection (same driver/host/database, dedicated credentials) used for all executions. In the database, grant that role only GRANT SELECT, USAGE:

-- MySQL
CREATE USER 'blunx_readonly'@'%' IDENTIFIED BY 'strong_password';
GRANT SELECT ON your_database.* TO 'blunx_readonly'@'%';

-- PostgreSQL
CREATE ROLE blunx_readonly LOGIN PASSWORD 'strong_password';
GRANT CONNECT ON DATABASE your_database TO blunx_readonly;
GRANT USAGE ON SCHEMA public TO blunx_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO blunx_readonly;

3. Per-role access rules (RBAC)

The config/blunx_access.php file defines, per role, the forbidden tables and columns and the row-level filtering. See the Configuration section for the full syntax. The role comes from getUserRoleName() on your User model.

• Forbidden tables: never scanned nor exposed to the LLM.
• Forbidden columns: masked ('*' pattern = all tables).
• Row-level filtering: the USER_ID placeholder is replaced by the logged-in user's ID (e.g. a sales rep only sees orders.user_id = themselves).

4. Authentication

In cross-origin setups, the backend must accept credentials: include (Access-Control-Allow-Credentials + an explicit origin, not *) and the Accept, Content-Type, X-Requested-With headers (CORS preflight).

5. Other protections

• Rate limiting: 60 requests/min/IP on the local /api/blunx/* group (Laravel throttle; in Node, add your own rate limiter, e.g. express-rate-limit), except the Stripe webhook (not concerned here).
• SQL validation: double check (client + server), a non-SELECT query is never executed.
• PostgreSQL schema: the scan only touches the configured schema (BLUNX_PGSQL_SCHEMA), never the others.
• CSRF: the blunx group mirrors web without CSRF (session auth is enough for this AJAX API).

LLM providers

Choose your provider through the driver and the endpoint. The openai adapter is "OpenAI-compatible": it works with almost every provider, proprietary or open-source.

Provider table

Configuring a provider

Example: DeepSeek (OpenAI-compatible API)

BLUNX_LLM_DRIVER=openai
BLUNX_LLM_ENDPOINT=https://api.deepseek.com/v1
BLUNX_LLM_MODEL=deepseek-chat
BLUNX_LLM_API_KEY=sk-xxxxxxxxxxxx
BLUNX_LLM_SUPPORTS_JSON_FORMAT=true

Example: local Ollama (zero cloud dependency)

BLUNX_LLM_DRIVER=openai
BLUNX_LLM_ENDPOINT=http://localhost:11434/v1
BLUNX_LLM_MODEL=llama3.1
BLUNX_LLM_API_KEY=ollama          # unused value, may stay empty
BLUNX_LLM_SUPPORTS_JSON_FORMAT=true

Example: Groq

BLUNX_LLM_DRIVER=openai
BLUNX_LLM_ENDPOINT=https://api.groq.com/openai/v1
BLUNX_LLM_MODEL=llama-3.3-70b-versatile
BLUNX_LLM_API_KEY=gsk_xxxxxxxxxxxx
BLUNX_LLM_SUPPORTS_JSON_FORMAT=true

Driver details

supports_json_format

Indicates whether the model supports the response_format: json_object mode. Modern models (GPT-4o, DeepSeek, Groq...) support it (true); some older local models do not. If the model does not support it, set false so that the pipeline asks for JSON in natural language rather than in structured mode.

Errors & troubleshooting

Organized by layer: Blunx server (HTTP), backend (Laravel / Node), SSE and Web SDK. Look for the HTTP code first, then the layer concerned.

1 · Blunx server HTTP codes

Shared by both backends - returned by the /api/v1/* hub:

2 · Backend

Both SDKs throw an exception with a human-readable message (the server message takes precedence when present):

401 => "Invalid or expired API key"
402 => "Billing inactive. Please check your subscription."
403 => "Application suspended. Contact support."
429 => "Quota exceeded. Please wait before retrying."
422 => "LLM configuration missing. Check your settings."
default => "AI service error. Please try again later."

try {
  await blunx.api.someCall();
} catch (e) {
  if (e instanceof BlunxError) {
    console.error(e.statusCode, e.message); // e.g. 401 "Invalid or expired API key"
  }
}

3 · SSE errors

• error event: {message, code, fields, plan, limit, used}.
• HTTP ≥ 400: extraction of message / error / detail.
• Network error: cURL error: ... (PHP) / fetch failed (Node).
• SCHEMA_NOT_FOUND: automatic retry without schema_id.

4 · Web SDK errors

5 · Common integration errors

Versions & updates

Web SDK versioning policy and backend SDK updates.

Versioning policy

The Web SDK follows semantic versioning (MAJOR.MINOR.PATCH):

• Patch: non-breaking bugfix (no action required).
• Minor: new backwards-compatible feature.
• Major: breaking change (public API, REST contract, navigation).

Web SDK updates

Web SDK changelog

Laravel package

• Update with composer update blunx/ai.
• Check the version: composer show blunx/ai.
• After a major update, re-check the published config/blunx.php (the published file is not overwritten automatically).

Support

A problem this documentation does not solve? The Blunx team replies within 24 hours.

Licence: MIT -© 2026 BlunxAI. Laravel package: blunx/ai · Web SDK : @blunx/web-sdk.