🔍 ShellDetect — AI Destekli AML Uyum Platformu

ShellDetect, Türkiye'deki KOBİ'lerde kara para aklama (AML) faaliyetlerini makine öğrenmesi ve büyük dil modelleriyle otomatik olarak tespit eden, MASAK mevzuatına uygun şüpheli işlem raporu (STR) üreten uçtan uca bir yapay zeka platformudur.

---

🚀 Özellikler

Modül	Açıklama
📊 Anomali Tespiti	Isolation Forest + SHAP ile açıklanabilir ML modeli
🕸️ Ağ Analizi	Tedarikçi ağlarında naylon fatura tespiti
📚 RAG Pipeline	ChromaDB + multilingual embedding ile MASAK mevzuatı arama
🤖 Multi-Agent	4 ajanın deterministik zinciri: Analist → Araştırmacı → Karar → Rapor
📄 STR Raporu	Gemini Flash ile otomatik MASAK Şüpheli İşlem Raporu üretimi
🎨 Streamlit UI	Gerçek zamanlı interaktif analiz paneli

---

🏗️ Proje Mimarisi

shelldetect/
├── app/
│   └── streamlit_app.py        # Ana kullanıcı arayüzü (5 sekme)
├── src/
│   ├── agents/
│   │   └── orchestrator.py     # 4-ajan multi-agent zinciri
│   ├── data_generation/        # Sentetik KOBİ verisi üretimi
│   ├── features/
│   │   ├── risk_score.py       # Kural tabanlı MASAK risk skoru
│   │   ├── norm_deviation.py   # Sektör normu sapma analizi
│   │   └── feature_pipeline.py # Scikit-learn preprocessing pipeline
│   ├── models/
│   │   ├── anomaly_detector.py # Isolation Forest + SHAP
│   │   ├── network_analysis.py # NetworkX tedarikçi ağı
│   │   └── seasonality.py      # Mevsimsellik anomali tespiti
│   ├── rag/
│   │   ├── ingest.py           # ChromaDB vektör indexleme
│   │   └── retriever.py        # Semantik bağlam arama
│   └── report/
│       └── generator.py        # Gemini ile STR raporu üretimi
├── data/
│   ├── raw/                    # Ham veri (firms, transactions, suppliers)
│   ├── rag_docs/               # MASAK kriterleri, vaka örnekleri (TXT)
│   └── processed/              # Model çıktıları (results.csv vb.)
├── .env.example                # Ortam değişkenleri şablonu
└── requirements.txt

---

⚙️ Kurulum

1. Depoyu klonlayın

git clone https://github.com/kullanici_adi/shelldetect.git
cd shelldetect

2. Sanal ortam oluşturun

python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate  # Linux/macOS

3. Bağımlılıkları yükleyin

pip install -r requirements.txt

4. API anahtarlarını ayarlayın

cp .env.example .env
# .env dosyasını açıp GEMINI_API_KEY değerini doldurun

.env dosyası içeriği:

GEMINI_API_KEY=your_api_key_here

---

🔄 Veri Pipeline'ını Çalıştırma (İlk Kurulum)

Eğer data/processed/ klasörü yoksa aşağıdaki adımları sırayla çalıştırın:

# 1. Sentetik veri üret
python src/data_generation/generate_firms.py
python src/data_generation/generate_transactions.py
python src/data_generation/generate_suppliers.py
python src/data_generation/generate_sector_norms.py

# 2. Feature engineering
python src/features/risk_score.py
python src/features/norm_deviation.py
python src/features/feature_pipeline.py

# 3. Model eğitimi
python src/models/anomaly_detector.py
python src/models/network_analysis.py
python src/models/seasonality.py

# 4. RAG vektör veritabanını oluştur
python src/rag/ingest.py

---

▶️ Uygulamayı Başlatma

streamlit run app/streamlit_app.py

Tarayıcıda http://localhost:8501 adresini açın.

---

🤖 Multi-Agent Akışı

Kullanıcı Firma Seçimi
        │
        ▼
┌─────────────────┐
│  Analist Ajan   │  ML anomali skoru + SHAP açıklaması
└────────┬────────┘
         │
         ▼
┌─────────────────────┐
│  Araştırmacı Ajan   │  ChromaDB'den MASAK mevzuatı + sektör normu
└────────┬────────────┘
         │
         ▼
┌────────────────────┐
│  Karar Verici Ajan │  AML örüntü sınıflandırması + risk kararı
└────────┬───────────┘
         │
         ▼
┌──────────────────────┐
│  Rapor Yazarı Ajan   │  Gemini Flash → Resmi MASAK STR Raporu
└──────────────────────┘

---

🧠 Kullanılan Teknolojiler

• ML: Scikit-learn (Isolation Forest), SHAP
• LLM: Google Gemini Flash
• RAG: ChromaDB, sentence-transformers (paraphrase-multilingual-MiniLM-L12-v2)
• Orchestration: LangChain 0.3 (tool dekoratörü)
• UI: Streamlit, Plotly
• Ağ Analizi: NetworkX

---

📋 Uygulama Sekmeleri

Sekme	İçerik
📊 Genel Bakış	Anomali skoru dağılımı, sektörel risk, izleme listesi
🔍 İşletme Analizi	Firma profil kartı, SHAP grafiği, radar chart, ciro grafisi
🕸️ Ağ Görselleştirme	Tedarikçi ağ grafiği, genç tedarikçi tespiti
📄 Rapor	AI ile MASAK STR raporu üretimi ve indirme
🤖 Ajan Analizi	Multi-agent orkestrasyonu canlı demo

---

⚠️ Önemli Notlar

• Bu platform yapay zeka destekli ön analiz aracıdır. Nihai karar yetkili uyum uzmanına aittir.
• Üretilen raporlar MASAK'a doğrudan gönderilemez, yetkili uyum uzmanı tarafından onaylanmalıdır.
• Veriler sentetik olarak üretilmiş olup gerçek firma verilerini temsil etmemektedir.