Enterprise AI Business Intelligence Platform

A production-grade AI-powered Business Intelligence platform combining JWT-secured REST APIs, enterprise Role-Based Access Control (RBAC), a Multi-Agent AI Copilot, Star Schema data warehousing, ETL ingestion, and production-ready infrastructure — v1.0.5 Full Async Migration & Stability Release.

Live Demo

The full backend is deployed and publicly testable — no cloning or local setup required.

Swagger UI: ai-bi-platform-ki1b.onrender.com/docs

Try it directly:

POST /copilot/query — ask a natural language business question
GET /dashboard/kpis — live KPIs computed from real warehouse data
GET /health — service health check

Note: The platform is hosted on Render's free tier. If the first request takes 30–60 seconds to respond, the server is waking up from sleep — subsequent requests will be instant.

Quick Start — No Setup Required

The platform is live and publicly testable in under a minute:

1. Open Swagger UI ai-bi-platform-ki1b.onrender.com/docs

If the page takes 30–60 seconds to load, the server is waking up — wait and refresh.

2. Log in with the demo account

Open POST /auth/login → Try it out
Enter the following credentials:

username: demo@enterprise-bi.com
password: Demo@12345

Click Execute and copy the access_token from the response body

3. Authorize Swagger with the token

Click the green Authorize button (top right of the Swagger page)
Paste the same demo credentials (username / password) into the OAuth2 form
Click Authorize → then Close

You are now authenticated. All protected endpoints are unlocked.

This is a shared demo account for evaluation purposes. For production use, register your own account via POST /auth/register.

4. Try the AI Copilot

POST /copilot/query → Try it out → Execute:

{
  "question": "What are the top products by revenue?"
}

5. Check live KPIs

GET /dashboard/kpis → Try it out → Execute — returns real warehouse metrics instantly.

Overview

The Enterprise AI Business Intelligence Platform is a production-oriented backend system designed for organizations that need intelligent, natural-language access to their data. It is not a simple dashboard — it is a modular, layered backend that provides:

Secure JWT authentication with Access & Refresh Tokens
Enterprise Role-Based Access Control (RBAC)
Production-grade authorization dependency layer
A fully orchestrated Multi-Agent AI Copilot pipeline
Star schema data warehouse with CSV ingestion via ETL
Dashboard and forecasting APIs backed by real analytics services
A pluggable LLM provider layer ready for OpenAI, Azure, Anthropic, and local models
Enterprise infrastructure: structured logging, request tracking, health monitoring, feature flags

Version 1 delivers all of this as a complete, runnable backend. Future versions will extend it toward autonomous decision intelligence.

Architecture

                           ┌──────────────────────┐
                           │      Swagger UI       │
                           └──────────┬────────────┘
                                      │
                                      ▼
                         ┌────────────────────────┐
                         │       FastAPI          │
                         │  Middleware Pipeline   │
                         │  RequestID │ Timing    │
                         │  Logging   │ Exception │
                         └──────────┬─────────────┘
                                    │
       ┌──────────────┬─────────────┼──────────────┬─────────────┐
       ▼              ▼             ▼              ▼             ▼
   Auth API     Copilot API   Dashboard API   Ingest API   Health API
       │              │
       ▼              ▼
  Auth Service   CopilotEngine
       │              │
       ▼         ┌────┴──────────────────────┐
  PostgreSQL     │   Multi-Agent Pipeline    │
  (User Table)   │                           │
                 │  Intent Classifier        │
                 │  Context Builder          │
                 │  Planner Agent            │
                 │  Execution Engine         │
                 │  ├── Retriever Agent      │
                 │  ├── SQL Agent            │
                 │  ├── Analytics Agent      │
                 │  └── Response Agent       │
                 │  Prompt Builder           │
                 │  LLM Provider Layer       │
                 └────────────┬──────────────┘
                              │
                    ┌─────────┴──────────┐
                    │   Data Platform    │
                    │  ETL Pipeline      │
                    │  Star Schema       │
                    │  PostgreSQL        │
                    └────────────────────┘

Multi-Agent Pipeline

User Question
      │
      ▼
Intent Classifier  (rule-based: sales / product / region / KPI / trend / summary)
      │
      ▼
Context Builder    (semantic retrieval, session context)
      │
      ▼
Planner Agent      (builds execution plan)
      │
      ▼
Execution Engine   (runs agents from registry)
      │
      ├── Retriever Agent   (FAISS vector retrieval)
      ├── SQL Agent         (generates, validates, executes SQL)
      ├── Analytics Agent   (KPI / stats aggregation)
      └── Response Agent    (formats final output)
      │
      ▼
Prompt Builder     (enterprise prompt engineering)
      │
      ▼
LLM Provider       (OpenAI / Mock — factory pattern)
      │
      ▼
Enterprise Response  (answer + confidence + cited sources)

Features

Authentication

JWT Authentication (Access + Refresh Tokens)
Refresh Token rotation endpoint
Enterprise Role-Based Access Control (RBAC)
Centralized authorization dependency layer
Protected API endpoints with Admin / Analyst / User permissions
OAuth2 Password Flow integration with Swagger UI
Secure password hashing with bcrypt
Production-ready CORS whitelist configuration

Enterprise AI Copilot

Intent Classification — rule-based classifier covering sales, product, region, KPI, trend, and summary intents with confidence scoring
Context Builder — builds retrieval context per question and session
Planner Agent — generates structured execution plans
Execution Engine — fully async dispatch of agents from an extensible registry; transparently awaits both sync and async agents
Agent Registry — Retriever, SQL, Analytics, Response agents
SQL Agent — schema-aware, LLM-backed SQL generation with a safe, schema-aware rule-based fallback whenever the LLM is unavailable or returns unsafe SQL
Prompt Builder — enterprise prompt templates
Conversation Memory — SQLite-backed, TTL-bound session history with automatic garbage collection (collect_garbage()); all disk I/O runs off the event loop via asyncio.to_thread
Response Pipeline — citation engine, confidence scoring, hallucination guard, response validator
LLM Provider Layer — factory pattern; OpenAI provider implemented; mock provider echoes real warehouse data for keyless demos; ready for Azure, Anthropic, Ollama

Dashboard & Analytics

KPI engine (total revenue, order count, averages)
Sales by region, top products, monthly sales
Chart-ready dataset responses for frontend integration
Executive summary endpoint
Revenue forecast, growth forecast, executive forecast

Data Platform

CSV upload endpoint with file validation and configurable size limit (MAX_UPLOAD_MB)
ETL pipeline: CSVLoader → DataTransformer → WarehouseLoader
Async batch warehouse loading via bulk_insert_mappings, run through AsyncSession
PostgreSQL star schema warehouse with Alembic migrations
Dimension tables: dim_customer, dim_product, dim_region, dim_channel, dim_date
Fact table: fact_sales (quantity, amount, UUID foreign keys, audit timestamps, indexed)

Enterprise Infrastructure

CORS middleware with configurable origins
SQLAlchemy connection pooling
Four middleware layers: RequestID, Timing, Logging, Exception
Health checker with live database probe and metrics collection
Feature flags: SQL Agent, RAG, Analytics, Streaming, Cache, Debug
Environment separation: development / testing / staging / production
Structured logging via Loguru
Makefile for common dev operations (run, build, test, lint, format)

Tech Stack

Layer	Technologies
Backend	Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Pydantic v2, Pydantic Settings, Alembic, Uvicorn
Auth	JWT (python-jose), bcrypt, OAuth2 Password Flow
AI / ML	Multi-Agent Architecture (fully async pipeline), FAISS, Sentence Transformers, RAG, LangChain
LLM	OpenAI SDK (gpt-4.1-mini), Mock Provider, Factory Pattern (sync- and async-compatible)
Data	PostgreSQL (asyncpg driver), Star Schema, Pandas, NumPy, Scikit-Learn, OpenPyXL
Infrastructure	Docker, Docker Compose, Loguru, psutil, Feature Flags
Dev Tools	Git, GitHub, Pytest, Black, Ruff, VS Code, Makefile

Project Structure

Enterprise-AI-Business-Intelligence-Platform/
├── app/
│   ├── main.py
│   ├── config.py
│   ├── database.py
│   ├── security.py
│   ├── core/
│   │   ├── settings.py
│   │   ├── environment.py
│   │   ├── feature_flags.py
│   │   ├── logging.py
│   │   └── constants.py
│   ├── middleware/
│   │   ├── request_id.py
│   │   ├── timing.py
│   │   ├── logging.py
│   │   └── exception.py
│   ├── routers/
│   │   ├── auth.py
│   │   ├── copilot.py
│   │   ├── dashboard.py
│   │   ├── ingest.py
│   │   ├── ai.py
│   │   └── health.py
│   ├── services/
│   │   ├── auth.py
│   │   ├── analytics/
│   │   │   ├── kpi.py
│   │   │   ├── stats.py
│   │   │   ├── charts.py
│   │   │   └── forecast.py
│   │   ├── etl/
│   │   │   ├── csv_loader.py
│   │   │   ├── transformer.py
│   │   │   └── warehouse_loader.py
│   │   └── ai/
│   │       ├── embeddings.py
│   │       ├── insights.py
│   │       ├── retrieval/
│   │       │   ├── base.py
│   │       │   ├── faiss.py
│   │       │   └── manager.py
│   │       ├── vector_store/
│   │       │   ├── faiss_store.py
│   │       │   ├── knowledge_base.py
│   │       │   ├── index_builder.py
│   │       │   └── persistence/
│   │       ├── knowledge/
│   │       │   ├── engine.py
│   │       │   ├── kpi.py
│   │       │   ├── product.py
│   │       │   └── region.py
│   │       ├── providers/
│   │       │   ├── base.py
│   │       │   ├── factory.py
│   │       │   ├── mock_provider.py
│   │       │   └── openai_provider.py
│   │       └── copilot/
│   │           ├── engine.py
│   │           ├── service.py
│   │           ├── intent/
│   │           ├── context/
│   │           ├── context_runtime/
│   │           ├── planner/
│   │           ├── executor/
│   │           ├── prompt/
│   │           ├── memory/
│   │           ├── response/
│   │           ├── tools/
│   │           └── agents/
│   │               ├── planner/
│   │               ├── sql/
│   │               ├── retriever/
│   │               ├── analytics/
│   │               └── response/
│   ├── models/
│   │   ├── user.py
│   │   └── warehouse.py
│   ├── schemas/
│   ├── monitoring/
│   │   ├── health.py
│   │   └── metrics.py
│   ├── utils/
│   │   └── logger.py
│   └── dependencies/
│       ├── auth.py
│       ├── rate_limit.py
│       └── rbac.py
├── alembic/
│   └── versions/
│       └── 001_initial_star_schema.py
├── tests/
│   └── manual/
├── requirements/
│   ├── base.txt
│   ├── ai.txt
│   ├── dev.txt
│   └── all.txt
├── docker-compose.yml
├── dockerfile
└── Makefile

Screenshots

Swagger UI Overview

Authentication Endpoints

Enterprise Copilot Endpoints

Dashboard Endpoints

Live AI Copilot Query

CSV Ingestion

Live Dashboard KPIs

Getting Started

Prerequisites

Python 3.12+
Docker & Docker Compose
PostgreSQL 15+ (or use Docker Compose — recommended)

Installation

# Clone the repository
git clone https://github.com/Mehdiest/Enterprise-AI-Business-Intelligence-Platform.git
cd Enterprise-AI-Business-Intelligence-Platform

Environment Variables

Create a .env file in the project root (see .env.example):

PROJECT_NAME=AI Business Intelligence Platform
API_V1_PREFIX=/api/v1
APP_ENV=development

POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=ai_bi
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres

SECRET_KEY=replace-with-a-random-48-byte-token
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

CORS_ORIGINS=*
MAX_UPLOAD_MB=10

OPENAI_API_KEY=

Leave OPENAI_API_KEY empty to use the mock provider — it echoes real warehouse query results for demo purposes. Set APP_ENV=production to enforce a strong SECRET_KEY and disable automatic schema creation.

Docker Setup (Recommended)

# Build and start all services
docker compose build
docker compose up

# Or using Makefile
make docker-build
make docker-up

# View logs
make docker-logs

# Stop
make docker-down

Local Setup

pip install -r requirements/base.txt
uvicorn app.main:app --reload

# Or
make install
make run

API Documentation

Interface	URL
Swagger UI	`http://localhost:8000/docs`
ReDoc	`http://localhost:8000/redoc`
Health Check	`http://localhost:8000/health`

Authentication Workflow

The platform uses OAuth2 Password Flow with JWT tokens. Most endpoints are protected and require a valid token.

Register

POST /auth/register
Content-Type: application/json

{
  "full_name": "Your Name",
  "email": "you@example.com",
  "password": "yourpassword"
}

Login

POST /auth/login

{ "access_token": "eyJ...", "token_type": "bearer" }

Refresh Access Token

POST /auth/refresh

{
    "refresh_token":"..."
}


**Protected Endpoints** — ETL ingestion and Copilot endpoints require authentication. Pass the token as a Bearer header:
```bash
curl -H "Authorization: Bearer <your_token>" \
     -X POST http://localhost:8000/copilot/query \
     -H "Content-Type: application/json" \
     -d '{"question": "What are the top products by revenue?"}'

Swagger Authorization — click Authorize, enter your credentials. Swagger automatically stores the JWT for all subsequent requests.

API Endpoints

Authentication

Method	Endpoint	Description
POST	`/auth/register`	Register new account
POST	`/auth/login`	Obtain access & refresh tokens
POST	`/auth/refresh`	Refresh access token
GET	`/auth/me`	Current authenticated user

AI Copilot

Method	Endpoint	Description
POST	`/copilot/query`	Submit a natural language question

Example Request:

curl -X POST http://localhost:8000/copilot/query \
  -H "Content-Type: application/json" \
  -d '{"question": "What are the top products by revenue?"}'

Example Response:

{
  "answer": "Based on the warehouse data, the top products by revenue are...",
  "confidence": 0.95,
  "sources": [
    { "id": "1", "text": "fact_sales joined with dim_product", "score": 1.0 }
  ]
}

Dashboard & Analytics

Method	Endpoint	Description
GET	`/dashboard/kpis`	Enterprise KPI metrics
GET	`/dashboard/sales-by-region`	Regional sales breakdown
GET	`/dashboard/top-products`	Top products by revenue
GET	`/dashboard/monthly-sales`	Monthly sales trends
GET	`/dashboard/chart/sales-by-region`	Chart-ready regional data
GET	`/dashboard/chart/top-products`	Chart-ready product data
GET	`/dashboard/chart/monthly-sales`	Chart-ready monthly data
GET	`/dashboard/chart/executive-summary`	Executive summary
GET	`/dashboard/forecast/revenue`	Revenue forecast
GET	`/dashboard/forecast/growth`	Growth forecast
GET	`/dashboard/forecast/executive-forecast`	Executive forecast

Data Ingestion

Method	Endpoint	Description
POST	`/ingest/csv`	Upload CSV and load into warehouse

Health

Method	Endpoint	Description
GET	`/health`	Health check with DB probe and metrics
GET	`/`	Root liveness check

Security

Refresh Token authentication flow
Enterprise Role-Based Access Control (RBAC)
Centralized authorization dependency (RoleRequired)
Endpoint-level permission enforcement (Admin / Analyst / User)
SQL parsing and validation using sqlparse
SQLAlchemy connection pooling for production workloads
Protected endpoints via FastAPI dependency injection (get_current_user)
Inactive-user check — disabled accounts are blocked at token validation
Login rate limiting — sliding-window throttle prevents brute-force attacks
CORS middleware with configurable allowed origins (CORS_ORIGINS)
SECRET_KEY startup guard — rejects known-insecure defaults in production
Upload size limit — configurable MAX_UPLOAD_MB with streamed enforcement
Environment-aware schema management — create_all disabled in production
Authentication required for ETL ingestion and Copilot endpoints
No secrets in source code — environment variable management only
SQLAlchemy ORM prevents SQL injection on application queries
Global exception middleware prevents stack trace leakage — full traces available in server logs only
Invalid CSV uploads return HTTP 400 instead of exposing internal errors

Roadmap

Version	Status	Focus
v1.0.0	✅ Released	JWT Auth, Multi-Agent Copilot, Star Schema, ETL, Dashboard APIs, Forecasting, Docker
v1.0.2	✅ Released	Security hardening — protected endpoints, safe exception handling, HTTP 400 on bad CSV
v1.0.3	✅ Released	Copilot data pipeline — SQL results flow into responses; CORS, rate limiting, upload limits, SECRET_KEY guard, duplicate module cleanup
v1.0.4	✅ Released	Enterprise RBAC, Refresh Token flow, SQL Validator, SQLAlchemy Connection Pooling, Production Authorization
v1.0.5	✅ Released	Full async migration — `asyncpg` engine, async-compatible auth/ingest/dashboard/insights routers, async batch warehouse loading, schema-aware LLM-backed SQL generation with safe fallback, SQLite-backed TTL conversation memory with non-blocking I/O
v1.1.0	🔜 Planned	Live SQL Tool Calling, Real RAG Knowledge Base, Persistent Conversation Memory
v1.2.0	🔜 Planned	Streaming Responses, Multi-Provider Routing, Agent Orchestration
v2.0	🔭 Vision	Autonomous Decision Intelligence

Changelog

v1.0.5 — Full Async Migration & Stability Release

Database — migrated from a sync psycopg2 engine to create_async_engine + async_sessionmaker (asyncpg driver); application lifecycle now creates/disposes the engine through FastAPI's async lifespan handler.
Routers — auth, ingest, dashboard, and ai/insights fully converted to AsyncSession.
Warehouse Loader — rewritten for async batch loading via bulk_insert_mappings, run through AsyncSession.run_sync.
SQL Agent — SQL generation is now schema-aware and LLM-backed, with a safe rule-based fallback whenever the LLM is unavailable, errors, or returns unsafe SQL.
Copilot Execution Engine — dispatches both sync and async agents transparently; the full pipeline (Retriever → SQL → Analytics → Response) is now async end-to-end.
Conversation Memory — moved from an in-memory dict to a SQLite-backed store with TTL expiry and collect_garbage(); all disk I/O now runs off the event loop via asyncio.to_thread to avoid blocking concurrent requests.
Session handling — expire_on_commit=False set on the session factory to prevent unawaited lazy-loads on ORM attributes accessed after a commit.

Contributing

Contributions, issues, and feature requests are welcome. Please open an issue first to discuss what you would like to change.

Fork the repository
Create your feature branch (git checkout -b feature/your-feature)
Commit your changes (git commit -m 'feat: add your feature')
Push to the branch (git push origin feature/your-feature)
Open a Pull Request

License

This project is licensed under the MIT License. See LICENSE for details.

Built with production standards — clean architecture, layered services, and a modular AI pipeline designed to scale from a single deployment to a full enterprise decision intelligence system.

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github/workflows		.github/workflows
alembic/versions		alembic/versions
app		app
assets/screenshots		assets/screenshots
requirements		requirements
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.memory.sqlite3		.memory.sqlite3
Dockerfile		Dockerfile
INSTALL.md		INSTALL.md
LICENSE		LICENSE
Makefile		Makefile
PROJECT_STRUCTURE.md		PROJECT_STRUCTURE.md
README.md		README.md
docker-compose.yml		docker-compose.yml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
ruff.toml		ruff.toml

Folders and files

Latest commit

History

Repository files navigation

Enterprise AI Business Intelligence Platform

Live Demo

Quick Start — No Setup Required

Overview

Architecture

Multi-Agent Pipeline

Features

Authentication

Enterprise AI Copilot

Dashboard & Analytics

Data Platform

Enterprise Infrastructure

Tech Stack

Project Structure

Screenshots

Getting Started

Prerequisites

Installation

Environment Variables

Docker Setup (Recommended)

Local Setup

API Documentation

Authentication Workflow

API Endpoints

Authentication

AI Copilot

Dashboard & Analytics

Data Ingestion

Health

Security

Roadmap

Changelog

v1.0.5 — Full Async Migration & Stability Release

Contributing

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages