🤖 Koopilot

Kadın Kooperatifleri için AI Destekli Sipariş, Stok ve Kargo Operasyon Ajanı ve Yönetim Paneli

WhatssApp, Telegram gibi mesaj kanallarından gelen müşteri mesajlarını siparişe dönüştürür,
stok kontrol eder, kargo sorularını cevaplar ve yöneticiden onay alarak aksiyon üretir.

Web sitesi: https://koopilot.vercel.app/

🔴 Problem

Kadın kooperatifleri ve küçük e-ticaret yapan KOBİ'ler, sipariş yönetimini WhatsApp, Telegram Instagram DM, mail ve telefon üzerinden manuel olarak yürütüyor. Bu da karışıklıklara sebep oluyor.

Sorun	Etki
Siparişler WhatsApp ve Telegram'dan alınıyor	Kayıp siparişler, unutulan detaylar
Stok takibi Excel/defter ile yapılıyor	Stokta olmayan ürün satışa sunuluyor
"Kargom nerede?" soruları tek tek yanıtlanıyor	Saatler süren manuel iş yükü
Hangi ürünün çok gittiği bilinmiyor	Üretim planlaması yapılamıyor

6 Şubat depremi sonrası Hatay ve çevre illerdeki kadın kooperatifleri dijitalleşme desteğine ihtiyaç duyuyor. Koopilot bu boşluğu doldurmak için tasarlandı.

💡 Çözüm

Koopilot, kooperatiflerin günlük operasyonlarını yöneten, AI operasyon ajanına sahip bir yönetim panelidir.

Koopilot Ne Yapar?

Müşteri Mesajlarına Gemini 3.1 flash-lite ile cevap verir, niyet çıkarımı yapar. Müşterinin sipariş vermesine yardımcı olur ve gelen siparişleri "Siparişler" sayfasına taslak olarak ekler.

Özellik	Açıklama
📩 Mesaj Analizi	Serbest Türkçe müşteri mesajından niyet çıkarımı (sipariş, kargo, şikayet, soru)
🛒 Otomatik Sipariş Taslağı	Mesajdan ürün adı, adet, müşteri bilgilerini çıkarıp sipariş taslağı oluşturma
📦 Stok Kontrolü	Sipariş öncesi stok doğrulama ve alternatif ürün önerisi
🚚 Kargo Sorgulama	Müşterinin kargo durumunu sorgulayıp yanıt önerisi üretme
✅ Human-in-the-Loop	AI taslak oluşturur, insan onaylar — tam otomatik değil, güvenli
📊 Günlük Özet	Gün sonu: kaç sipariş, hangi ürünler çok soruldu, stok uyarıları
⚠️ Stok Uyarıları	Çok talep edilen ama stokta olmayan ürünler için otomatik uyarı

🎬 Demo Senaryosu

Senaryo: Müşteri mesajından sipariş taslağı oluşuyor

1. Mesaj Gelir:

"Merhaba, 2 kavanoz domates salçası ve 1 nar ekşisi almak istiyorum. Ankara'ya kargo olur mu?"

2. AI Analiz Eder:

{
  "intent": "new_order",
  "products": [
    {"name": "domates salçası", "quantity": 2},
    {"name": "nar ekşisi", "quantity": 1}
  ],
  "city": "Ankara",
  "missing_info": ["customer_name", "phone", "address"]
}

3. Stok Kontrol Edilir:

✅ Domates Salçası: 50 adet mevcut
✅ Nar Ekşisi: 30 adet mevcut

4. AI Cevap Önerisi Üretir:

"Merhaba! Domates salçamız ve nar ekşimiz stokta mevcut. Siparişinizi tamamlamak için ad-soyad, telefon ve açık adresinizi paylaşır mısınız? 🌿"

5. Kooperatif Yöneticisi Dashboard'dan Onaylar → Sipariş Kesinleşir

🏗️ Mimari

┌─────────────────────────────────────────────────────────┐
│                    KOOPILOT MİMARİSİ                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐    ┌──────────────┐    ┌───────────┐  │
│  │  WhatsApp    │    │   Telegram   │    │ Web Panel │  │
│  │  Adapter     │    │   Bot API    │    │ Test Akışı│  │
│  └──────┬───────┘    └──────┬───────┘    └─────┬─────┘  │
│         │                   │                  │        │
│         └───────────────────┼──────────────────┘        │
│                             │                           │
│                    ┌────────▼────────┐                   │
│                    │  Message Inbox  │                   │
│                    │   (Adapter)     │                   │
│                    └────────┬────────┘                   │
│                             │                           │
│          ┌──────────────────▼──────────────────┐        │
│          │         FastAPI Backend              │        │
│          │  ┌─────────────────────────────┐     │        │
│          │  │    Gemini AI Agent          │     │        │
│          │  │  • Intent Extraction        │     │        │
│          │  │  • Product Matching         │     │        │
│          │  │  • Reply Generation         │     │        │
│          │  │  • Function Calling         │     │        │
│          │  └─────────────────────────────┘     │        │
│          │  ┌──────────┐  ┌───────────────┐    │        │
│          │  │ Order    │  │ Inventory     │    │        │
│          │  │ Service  │  │ Service       │    │        │
│          │  └──────────┘  └───────────────┘    │        │
│          │  ┌──────────┐  ┌───────────────┐    │        │
│          │  │ Shipping │  │ Analytics     │    │        │
│          │  │ Mock API │  │ Service       │    │        │
│          │  └──────────┘  └───────────────┘    │        │
│          └──────────────────┬──────────────────┘        │
│                             │                           │
│                    ┌────────▼────────┐                   │
│                    │   SQLite DB     │                   │
│                    └─────────────────┘                   │
│                             │                           │
│          ┌──────────────────▼──────────────────┐        │
│          │      React Dashboard (Vite)         │        │
│          │  ┌─────────┐ ┌──────┐ ┌──────────┐  │        │
│          │  │ Mesajlar│ │ Stok │ │Siparişler│  │        │
│          │  └─────────┘ └──────┘ └──────────┘  │        │
│          │  ┌─────────┐ ┌──────────────────┐   │        │
│          │  │ Kargo   │ │  Günlük Özet     │   │        │
│          │  └─────────┘ └──────────────────┘   │        │
│          └─────────────────────────────────────┘        │
│                                                         │
└─────────────────────────────────────────────────────────┘

🛠 Teknoloji Yığını

Katman	Teknoloji	Neden?
Backend	FastAPI + Python 3.11+	Hackathon gereksinimi, hızlı API geliştirme, otomatik `/docs`
AI	Google Gemini 3.1 Flash-Lite	Düşük gecikmeli, düşük maliyetli, yapılandırılmış çıktı ve hafif ajan görevleri için uygun
Veritabanı	SQLite + SQLAlchemy ORM	Sıfır konfigürasyon, taşınabilir, hackathon için ideal
Frontend	React 18 + Vite	Hızlı geliştirme, modern araçlar, component tabanlı UI
Stil	CSS (Modern)	Temiz, hızlı, bağımlılık gerektirmeyen

🧠 Yapay Zeka Kullanımı

Koopilot'ta AI sadece "sohbet etmek" için kullanılmıyor. İş yapan bir ajan olarak çalışıyor:

AI Fonksiyonu	Açıklama
Niyet Çıkarımı	Serbest Türkçe mesajdan intent belirleme (sipariş, kargo, şikayet, soru)
Ürün Eşleştirme	"ev yapımı salça", "domates salçası", "acı salça" → katalogdaki doğru ürün
Bilgi Çıkarımı	Mesajdan ad, telefon, adres, şehir, ürün ve adet çıkarma
Eksik Bilgi Tespiti	Sipariş için gerekli ama mesajda olmayan bilgileri listeleme
Cevap Üretimi	Stok durumuna göre kişiselleştirilmiş, profesyonel cevap önerisi
Mesaj Önceliklendirme	Şikayet > Sipariş > Kargo sorusu > Genel soru
Günlük Özet	"Bugün 18 mesaj, 7 sipariş, 3 stok yetersizliği, en çok sorulan: nar ekşisi"
Sohbet Hafızası	Önceki mesajları bağlam olarak kullanarak tutarlı diyalog

Gemini Structured Output

Gemini'nin response_schema özelliği kullanılarak her yanıt yapılandırılmış JSON olarak alınır. Bu sayede AI çıktısı doğrudan iş mantığına aktarılır:

config={
    'response_mime_type': 'application/json',
    'response_schema': AIFinalResponse,  # Pydantic model
    'temperature': 0.1  # Düşük sıcaklık = tutarlı çıktı
}

🚀 Kurulum

Gereksinimler

Python 3.11 veya 3.12 önerilir
Node.js 18+
Gemini API Key (Google AI Studio'dan ücretsiz alınabilir)
Opsiyonel Telegram Bot Token (BotFather üzerinden alınabilir)

Backend

# 1. Repo'yu klonla
git clone https://github.com/YZTA-Hackathon-Koopilot/Koopilot.git
cd YZTA-Hackathon-Koopilot

# 2. Backend sanal ortam oluştur
cd backend
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. Bağımlılıkları yükle
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

# 4. API anahtarını ayarla
cp .env.example .env
# .env dosyasını aç ve GEMINI_API_KEY değerini gir
# Telegram gerçek kanal demosu için TELEGRAM_BOT_TOKEN değerini de ekleyebilirsin
# Telegram webhook güvenliği için TELEGRAM_WEBHOOK_SECRET değerini rastgele bir metin olarak belirle
# WhatsApp altyapısı için WHATSAPP_* değerleri .env.example içinde yer alır; token yoksa canlı WhatsApp bağlı değildir

# 5. Veritabanını başlat (demo verileriyle)
python db_init.py

# 6. Sunucuyu başlat
python -m uvicorn main:app --reload --port 8000

Backend çalıştıktan sonra: http://localhost:8000/docs adresinden etkileşimli API dokümantasyonuna erişebilirsiniz.

Frontend

# Ayrı bir terminal aç
cd frontend

# Bağımlılıkları yükle
npm install

# Geliştirme sunucusunu başlat
npm run dev

Frontend: http://localhost:5173 adresinde çalışacaktır.

🌐 Demoya Erişin

Backend: Render
Frontend: Vercel
Mesaj kanalı: Web panel operasyon ajanı + Telegram Bot API + WhatsApp webhook altyapısı

Backend:

https://koopilot-backend.onrender.com/
https://koopilot-backend.onrender.com/health
https://koopilot-backend.onrender.com/docs

Frontend:

https://koopilot.vercel.app/

📡 API Endpoints

Method	Endpoint	Açıklama
`GET`	`/health`	Canlı servis sağlık kontrolü
`POST`	`/ai/analyze-message`	Müşteri mesajını AI ile analiz et, niyet çıkar, aksiyon öner
`POST`	`/integrations/telegram/webhook`	Telegram mesajlarını Koopilot AI ajanına aktar
`GET`	`/integrations/telegram/status`	Telegram bot ve webhook durumunu göster
`POST`	`/integrations/telegram/setup-webhook`	Telegram webhook'unu canlı backend'e bağla
`POST`	`/integrations/telegram/delete-webhook`	Telegram webhook'unu kaldır
`GET`	`/integrations/channels`	Mesaj kanallarının gerçek bağlantı durumunu listele
`GET`	`/integrations/whatsapp/status`	WhatsApp entegrasyon durumunu göster
`GET`	`/integrations/whatsapp/webhook`	WhatsApp Business webhook doğrulaması
`POST`	`/integrations/whatsapp/webhook`	WhatsApp payload'ını Koopilot AI ajanına aktar
`GET`	`/inventory`	Tüm ürünleri ve stok durumlarını listele
`PUT`	`/inventory/{product_id}`	Ürün stok güncelle
`POST`	`/inventory/upload`	Excel/CSV ile toplu ürün yükle
`GET`	`/orders`	Tüm siparişleri listele
`PUT`	`/orders/{order_id}/approve`	Siparişi onayla ve stoktan düş
`GET`	`/shipping/status/{order_id}`	Mock kargo durumu sorgula
`GET`	`/ai/daily-summary`	Günlük AI özet raporu

💡 Tüm endpoint'lerin detaylı dokümantasyonu çalışır haldeyken /docs adresinden erişilebilir (FastAPI Swagger UI).

📁 Proje Yapısı

YZTA-Hackathon-Koopilot/
├── backend/
│   ├── main.py              # FastAPI uygulama giriş noktası ve route'lar
│   ├── ai_agent.py          # Gemini AI entegrasyonu ve mesaj analiz
│   ├── models.py            # SQLAlchemy veritabanı modelleri
│   ├── schemas.py           # Pydantic request/response şemaları
│   ├── database.py          # Veritabanı bağlantı konfigürasyonu
│   ├── db_init.py           # Demo verilerle veritabanı başlatma
│   ├── requirements.txt     # Python bağımlılıkları
│   ├── .env.example         # Ortam değişkenleri şablonu
│   └── .gitignore
├── frontend/
│   ├── index.html
│   ├── src/
│   │   ├── App.jsx          # Ana uygulama bileşeni
│   │   ├── main.jsx         # React giriş noktası
│   │   ├── index.css        # Global stiller ve tasarım sistemi
│   │   ├── components/      # UI bileşenleri
│   │   │   ├── Sidebar.jsx
│   │   │   ├── MessagePanel.jsx
│   │   │   ├── OrderPanel.jsx
│   │   │   ├── InventoryPanel.jsx
│   │   │   ├── ShippingPanel.jsx
│   │   │   └── DailySummary.jsx
│   │   └── services/
│   │       └── api.js       # Backend API iletişim katmanı
│   ├── package.json
│   └── vite.config.js
├── docs/
│   ├── assets/              # Logo, banner, screenshot'lar
│   ├── gorev-muhammed.md    # Muhammed görev planı
│   ├── gorev-kaan.md        # Kaan görev planı
│   └── gorev-zeynep.md      # Zeynep görev planı
├── .gitignore
└── README.md

👥 Takım

Üye	Rol	Sorumluluk
Muhammed Köseoğlu	Backend & AI	FastAPI, Gemini entegrasyonu, AI ajan geliştirme
Kaan	Frontend & UI/UX	React dashboard, kullanıcı deneyimi
Zeynep	Demo, Test & Sunum	Video, pitch deck, test, dokümantasyon

📄 Lisans

Bu proje MIT Lisansı altında lisanslanmıştır.

Koopilot — Kooperatiflerin dijital ekip arkadaşı 🌿
YZTA Hackathon 2026 | Google Yapay Zeka Teknoloji Akademisi

Name		Name	Last commit message	Last commit date
backend		backend
docs		docs
frontend		frontend
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
render.yaml		render.yaml
start.sh		start.sh
teknoloji_urunleri.csv		teknoloji_urunleri.csv

Navigation Menu

Repository navigation

About

Repository files navigation

🤖 Koopilot

Kadın Kooperatifleri için AI Destekli Sipariş, Stok ve Kargo Operasyon Ajanı ve Yönetim Paneli

📋 İçindekiler

🔴 Problem

💡 Çözüm

Koopilot Ne Yapar?

🎬 Demo Senaryosu

Senaryo: Müşteri mesajından sipariş taslağı oluşuyor

🏗️ Mimari

🛠 Teknoloji Yığını

🧠 Yapay Zeka Kullanımı

Gemini Structured Output

🚀 Kurulum

Gereksinimler

Backend

Frontend

🌐 Demoya Erişin

📡 API Endpoints

📁 Proje Yapısı

👥 Takım

📄 Lisans

About

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🤖 Koopilot

Kadın Kooperatifleri için AI Destekli Sipariş, Stok ve Kargo Operasyon Ajanı ve Yönetim Paneli

📋 İçindekiler

🔴 Problem

💡 Çözüm

Koopilot Ne Yapar?

🎬 Demo Senaryosu

Senaryo: Müşteri mesajından sipariş taslağı oluşuyor

🏗️ Mimari

🛠 Teknoloji Yığını

🧠 Yapay Zeka Kullanımı

Gemini Structured Output

🚀 Kurulum

Gereksinimler

Backend

Frontend

🌐 Demoya Erişin

📡 API Endpoints

📁 Proje Yapısı

👥 Takım

📄 Lisans

About

Topics

Resources

Stars

Watchers

Forks

Contributors

Languages