DataSage

DataSage, doğal dil ile sorulan analitik soruları güvenli PostgreSQL sorgularına dönüştüren, sorguyu çalıştıran ve sonucu tablo/grafik olarak sunan API-first bir analytics platformudur.

1. Proje Tanımı

DataSage nedir?

DataSage; kullanıcıların teknik SQL yazmadan, doğal dilde soru sorarak veri analizi yapabilmesini hedefleyen çok katmanlı bir uygulamadır.

Ne problemi çözer?

Analist veya iş kullanıcısının SQL bilmeden veri sorgulamasını sağlar
Doğal dil ile gelen isteği güvenli SQL akışına dönüştürür
Sonuçları tablo, metadata ve uygun olduğunda grafik olarak gösterir
Sorgu geçmişi, admin görünürlüğü ve schema görünümü ile operasyonel izlenebilirlik sunar

Natural language -> SQL yaklaşımı

Temel akış şu şekildedir:

Kullanıcı Angular arayüzünden doğal dilde soru sorar
.NET API isteği alır ve orkestrasyonu yönetir
FastAPI AI servisi soruyu SQL üretimine hazırlar
Gerekirse Ollama/SQLCoder ile SQL üretilir
.NET katmanı SQL güvenliğini doğrular
PostgreSQL üzerinde sorgu çalıştırılır
Sonuç satırları, çalışma metadata'sı ve chart payload frontend'e döner

2. Özellikler

Doğal dil ile sorgu desteği
Türkçe ve İngilizce soru desteği
SQL generation
Read-only SQL validation
PostgreSQL query execution
Result table rendering
Backend chart metadata generation
Query execution + result visualization
Query history
Admin panel
Schema viewer + schema refresh
JWT tabanlı giriş ve rol kontrolü
Türkçe destek için question normalizer
Desteklenen sorular için deterministic fast-path
Desteklenmeyen sorular için AI fallback via Ollama/SQLCoder

3. Mimari

Katmanlar

frontend/datasage-ui
- Angular tabanlı kullanıcı arayüzü
- Login, Query, History, Admin ve Access Denied ekranları
backend/src/DataSage.API
- HTTP giriş noktası
- Auth, authorization, orchestration ve API contract'ları
backend/src/DataSage.Application
- Abstraction ve DTO katmanı
backend/src/DataSage.Infrastructure
- AI client, SQL validator, query executor, log persistence, schema metadata, auth service
ai-service
- FastAPI tabanlı AI microservice
- SQL generation, repair ve prompt hazırlama
docker
- Docker Compose, PostgreSQL seed/init ve container runtime yapısı

Kullanılan Teknolojiler

Frontend: Angular
Backend API: .NET 8 ASP.NET Core Web API
AI Service: Python FastAPI
LLM Runtime: Ollama + SQLCoder
Database: PostgreSQL 16
Dev runtime: Docker Compose

Request Flow

User
  -> Frontend (Angular)
  -> Backend (.NET API)
  -> AI Service (FastAPI)
  -> SQL generation
  -> PostgreSQL execution
  -> Response (rows + metadata + chart)

Daha ayrıntılı akış:

user
  -> frontend
  -> backend
  -> ai-service
  -> SQL
  -> DB
  -> backend response
  -> frontend rendering

4. Türkçe Sorgu Desteği

Problem neydi?

İlk çalışan sürümde doğal dil -> SQL akışı ağırlıklı olarak İngilizce örnekler ve İngilizce schema grounding üzerinden ilerliyordu. Bu nedenle:

Türkçe sorgular bazen yavaş kalıyordu
Model niyeti yanlış yorumlayabiliyordu
Hatalı ya da alakasız SQL dönebiliyordu
Kullanıcı tarafında sorgu "takılıyormuş" gibi hissedilebiliyordu

Nasıl çözüldü?

Türkçe destek için kontrollü ve güvenli bir çözüm eklendi:

question normalizer
- Türkçe ve İngilizce desteklenen soru kalıplarını normalize eder
supported intents
- Bilinen analitik soruları kararlı intent'lere eşler
deterministic SQL
- Desteklenen intent'ler için doğrudan güvenilir SQL üretir
fallback AI
- Desteklenmeyen sorular mevcut Ollama/SQLCoder akışına düşer

Kullanılan yaklaşım

Önce soru normalize edilir
Desteklenen intent bulunursa deterministic fast-path çalışır
Intent desteklenmiyorsa mevcut AI generation akışı korunur
Orijinal kullanıcı sorusu mantıksal olarak korunur

Örnek eşleşmeler

en çok satan 5 ürün -> top 5 products by sales
kategoriye göre satışlar -> sales by category
satışa göre en iyi 5 çalışan -> top 5 employees by sales
aylık satış trendi -> monthly sales trend

Neden bu yaklaşım seçildi?

Mevcut İngilizce akışı bozmaz
SQL güvenliğini zayıflatmaz
Türkçe temel analitik sorularda gecikmeyi ciddi şekilde azaltır
Bakımı kolaydır
Genişletilebilir bir yapı sunar

5. Kurulum

Gereksinimler

Docker Desktop
.NET 8 SDK
Node.js + npm
Python 3.12+ veya mevcut lokal Python kurulumu

Ortam dosyası

Kök dizinde .env dosyasını oluştur:

Copy-Item .env.example .env

Docker ile tam kurulum

Tüm sistemi ayağa kaldır:

docker compose --env-file .env -f docker/docker-compose.yml up --build

İlk kurulumda model yoksa Ollama içine SQLCoder çek:

docker exec -it datasage-ollama ollama pull sqlcoder

Manuel geliştirme modu

Altyapı servisleri:

docker compose --env-file .env -f docker/docker-compose.yml up -d postgres ollama

Backend:

cd backend
dotnet restore
dotnet run --project src/DataSage.API --launch-profile http

AI service:

cd ai-service
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend:

cd frontend/datasage-ui
npm.cmd install --legacy-peer-deps
npm.cmd start

Portlar

Frontend UI: http://localhost:4200
Backend API Swagger: http://localhost:8080/swagger veya manuel modda http://localhost:5064/swagger
AI Service Docs: http://localhost:8000/docs
PostgreSQL: localhost:5432
Ollama: http://localhost:11434

6. Kullanım

Uygulamayı aç

UI: http://localhost:4200

Demo kullanıcılar

Admin
- kullanıcı adı: admin
- e-posta: admin@datasage.local
- şifre: Admin123!
User
- kullanıcı adı: analyst
- e-posta: user@datasage.local
- şifre: User123!

Örnek sorular

Türkçe:

en çok satan 5 ürün
kategoriye göre satışlar
satışa göre en iyi 5 çalışan
aylık satış trendi

İngilizce:

top 5 products by sales
sales by category
top 5 employees by sales
monthly sales trend

Query akışı

Giriş yap
Query sayfasına git
Soru alanına doğal dilde sorunu yaz
Run Query ile sorguyu gönder
SQL, execution metadata, table ve chart sonucunu incele

7. API Örnekleri

`POST /api/ai/query`

Request:

{
  "question": "en çok satan 5 ürün"
}

Örnek response:

{
  "sql": "SELECT products.product_id, products.product_name, SUM(order_details.unit_price * order_details.quantity * (1 - order_details.discount)) AS total_sales FROM products JOIN order_details ON products.product_id = order_details.product_id GROUP BY products.product_id, products.product_name ORDER BY total_sales DESC LIMIT 5;",
  "raw": "SELECT products.product_id, products.product_name, SUM(order_details.unit_price * order_details.quantity * (1 - order_details.discount)) AS total_sales FROM products JOIN order_details ON products.product_id = order_details.product_id GROUP BY products.product_id, products.product_name ORDER BY total_sales DESC LIMIT 5;",
  "columns": [
    "product_id",
    "product_name",
    "total_sales"
  ],
  "rows": [
    {
      "product_id": 12,
      "product_name": "Queso Manchego La Pastora",
      "total_sales": 2222.24
    }
  ],
  "rowCount": 5,
  "executionTimeMs": 38,
  "attemptCount": 1,
  "wasRepaired": false,
  "error": null,
  "chart": {
    "type": "bar",
    "title": "Top 5 Products By Sales",
    "xKey": "product_name",
    "yKeys": ["total_sales"]
  }
}

8. Test Sonuçları

Aşağıdaki Türkçe ve İngilizce örnekler doğrulandı:

Soru	Durum	Sonuç
`en çok satan 5 ürün`	OK	Doğru SQL + 5 satır
`kategoriye göre satışlar`	OK	Doğru SQL + kategori bazlı sonuç
`satışa göre en iyi 5 çalışan`	OK	Doğru SQL + 5 çalışan
`aylık satış trendi`	OK	Doğru SQL + line-chart uyumlu sonuç
`top 5 products by sales`	OK	Doğru SQL + 5 satır
`sales by category`	OK	Doğru SQL + kategori bazlı sonuç
`top 5 employees by sales`	OK	Doğru SQL + 5 çalışan
`monthly sales trend`	OK	Doğru SQL + line-chart uyumlu sonuç

Kısa özet:

Türkçe desteklenen intent'lerde hızlı ve deterministik sonuç alınıyor
İngilizce akış korunuyor
Query execution, history, admin ve auth akışı etkilenmiyor

9. Bilinen Limitler

Deterministic yaklaşım şu an yalnızca desteklenen intent seti için geçerli
Daha karmaşık Türkçe sorular AI fallback yoluna gider
Local model zaman zaman yavaş olabilir
AI fallback tam garantili değildir
Grafik seçimi deterministik kural tabanlıdır, AI tabanlı değildir

10. Gelecek Geliştirmeler

Türkçe intent kapsama alanını genişletmek
Daha zengin synonym ve domain terim desteği eklemek
Karmaşık Türkçe sorular için daha güçlü bilingual prompt tasarımı
AI accuracy ve repair kalitesini artırmak
Sorgu örnekleri ve intent kataloğunu genişletmek

11. Proje Yapısı

DataSage/
|-- backend/
|   |-- src/
|   |   |-- DataSage.API/
|   |   |-- DataSage.Application/
|   |   |-- DataSage.Domain/
|   |   `-- DataSage.Infrastructure/
|   `-- tests/
|-- frontend/
|   `-- datasage-ui/
|-- ai-service/
|   `-- app/
|-- docker/
|   `-- postgres/init/
|-- docs/
|-- .env.example
`-- README.md

Ek Notlar

Query guide ve queryable tables açıklamaları için docs/query-guide.md
Mimari kararlar için docs/architecture.md ve docs/decisions.md
Local development için seeded demo kullanıcılar yalnızca geliştirme amaçlıdır

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
ai-service		ai-service
backend		backend
docker		docker
docs		docs
frontend/datasage-ui		frontend/datasage-ui
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

DataSage

1. Proje Tanımı

DataSage nedir?

Ne problemi çözer?

Natural language -> SQL yaklaşımı

2. Özellikler

3. Mimari

Katmanlar

Kullanılan Teknolojiler

Request Flow

4. Türkçe Sorgu Desteği

Problem neydi?

Nasıl çözüldü?

Kullanılan yaklaşım

Örnek eşleşmeler

Neden bu yaklaşım seçildi?

5. Kurulum

Gereksinimler

Ortam dosyası

Docker ile tam kurulum

Manuel geliştirme modu

Portlar

6. Kullanım

Uygulamayı aç

Demo kullanıcılar

Örnek sorular

Query akışı

7. API Örnekleri

POST /api/ai/query

8. Test Sonuçları

9. Bilinen Limitler

10. Gelecek Geliştirmeler

11. Proje Yapısı

Ek Notlar

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`POST /api/ai/query`

Packages