Anon ERP NL2SQL Assistant

(OpenAI & Google Gemini – ERP-Agnostic, Secure, Anonymous)

---

🇬🇧 ENGLISH

1. What is this project?

Anon ERP NL2SQL Assistant is a fully anonymous, ERP-agnostic template that converts natural language questions into safe, read-only SQL queries for ERP reporting systems.

This repository is designed as a production-ready foundation, not a demo:

• No company name
• No ERP product name
• No real table/column names
• No IPs, credentials, or private endpoints

All real-world details are injected only via configuration files.

---

2. Who is this for?

👨‍💻 Software Engineers

• Clean, modular architecture
• Provider-agnostic LLM integration (OpenAI & Gemini)
• SQL safety layer (SELECT-only, allowlist-based)
• Easy to extend with caching, UI, or analytics layers

📊 ERP Consultants / Business Analysts

• Ask questions without writing SQL
• Control which ERP tables and columns are accessible
• Prevent destructive queries by design
• Use ERP terminology instead of technical SQL syntax

---

3. Core capabilities

• 🔍 Database schema introspection (allowlist-based)
• 🧠 Natural Language → SQL (NL2SQL)
• 🔐 SQL security guard:
  • SELECT only
  • No INSERT / UPDATE / DELETE / DROP / ALTER
  • No multi-statement queries
• 🔁 Single interface for OpenAI GPT and Google Gemini
• 🧾 Detailed usage logging (anonymous)
• 🏢 ERP-agnostic (works with any SQL-based ERP)

---

4. High-level architecture

User Question (Natural Language)
        ↓
Role & Permission Context
        ↓
Allowed ERP Schema (Allowlist)
        ↓
Prompt Construction
        ↓
LLM (OpenAI or Gemini)
        ↓
SQL Safety Guard
        ↓
(Optional) Database Execution
        ↓
Result + Logs

---

5. Why this is safe for ERP systems

• LLM never sees database names or credentials
• Only explicitly allowed tables/columns are exposed
• All generated SQL is validated before execution
• Read-only reporting use case by design

---

6. Project structure overview

app/
 ├─ main.py              # Application entry point
 ├─ api/                 # REST endpoints (/ask, /health)
 ├─ nl2sql/              # NL → SQL pipeline
 ├─ llm/                 # OpenAI & Gemini adapters
 ├─ db/                  # Database connection & execution
 ├─ schema/              # Schema introspection
 ├─ security/            # SQL guard & policies
 └─ core/                # Config, logging, shared utilities

policies/
 └─ allowlist.json       # ERP table/column permissions

---

7. Installation

python -m venv .venv
pip install -r requirements.txt
cp .env.example .env
python -m app.main

---

8. What YOU must customize after download (IMPORTANT)

🔧 1) .env file

You must edit:

• OPENAI_API_KEY or GEMINI_API_KEY
• DB_DIALECT (mssql / postgres / mysql)
• DB_DSN or connection parameters

🔧 2) policies/allowlist.json

ERP consultants define:

• Which tables are visible
• Which columns are allowed
• Optional column aliases (business-friendly names)

LLM cannot access anything outside this file.

🔧 3) Prompt rules (optional)

Developers may fine-tune:

• app/nl2sql/prompt_builder.py
• Add ERP-specific terminology
• Add KPI examples

🔧 4) Roles & permissions (optional)

Extend:

• security/roles.py to create roles like:
• finance
• sales
• warehouse
• management

🔧 5) UI / Output (optional)

• Add Excel / PDF export
• Add dashboard UI (React, Dash, etc.)
• Add query history page

---

9. Typical production additions

• Authentication via ERP user tables
• Query caching
• Column masking for sensitive data
• Multi-company / multi-year routing
• Audit dashboard

---

🇹🇷 TÜRKÇE

1. Bu proje nedir?

Anon ERP NL2SQL Assistant, ERP sistemleri üzerinde doğal dille SQL raporu oluşturmak için tasarlanmış, tamamen anonim ve ERP-bağımsız bir altyapıdır.

Bu repo:

• Şirket adı içermez
• ERP ürünü içermez
• Gerçek tablo / kolon içermez
• IP, şifre, kullanıcı bilgisi barındırmaz

---

2. Kimler için?

👨‍💻 Yazılımcılar

• Modüler mimari
• OpenAI & Gemini tek altyapı
• SQL güvenlik katmanı
• Kurumsal entegrasyona uygun

📊 ERP Danışmanları

• SQL yazmadan rapor
• Kontrollü tablo erişimi
• Veri silme riski olmadan analiz

---

3. Temel yetenekler

• Doğal dil → SQL
• Sadece SELECT sorguları
• Çoklu SQL engeli
• ERP-bağımsız yapı
• Güvenli loglama

---

4. Kurulumdan sonra SİZ ne yapacaksınız? (ÇOK ÖNEMLİ)

🧩 1) .env düzenlenecek

• API key girilecek
• DB bağlantısı yazılacak

🧩 2) allowlist.json doldurulacak

ERP danışmanı:

• Hangi tablolar?
• Hangi kolonlar?
• Hangi iş terimleri?

🧩 3) Prompt iyileştirme (opsiyonel)

• ERP terimleri
• KPI tanımları
• Tarih, para birimi kuralları

🧩 4) Yetki & rol genişletme

• Finans / Satış / Depo
• Yönetici rolleri

🧩 5) Çıktılar

• Excel
• PDF
• Dashboard

---

5. Son söz

Bu repo:

• Kurumsal ERP NL2SQL projeleri için
• Güvenli, anonim, sürdürülebilir
• Gerçek hayata uygun bir çekirdek mimaridir.

---