Bütçio — AI Destekli Kişisel Finans Asistanı

BTK Hackathon 2026 projesi. Streamlit + FastAPI + Flutter mobil shell; arka planda Gemini & LangChain ile çalışan çok-modlu (Bireysel / Aile / KOBİ) finans asistanı.

Hızlı Başlangıç

Gereksinimler

• Python 3.11+ (AI servisi + Streamlit)
• Java 17+ & Maven 3.8+ (opsiyonel — backend v2 iskeleti)
• Flutter 3.12+ (opsiyonel — mobil shell)
• Gemini API Key (ai-service/.env içine GEMINI_API_KEY=...)

1) AI Servisi (FastAPI)

cd ai-service
pip install -r requirements.txt
python -m uvicorn main:app --reload --port 8001

Sağlık kontrolü: http://localhost:8001/docs

2) Arayüz (Streamlit)

cd streamlit_app
pip install -r requirements.txt
python -m streamlit run app.py

Otomatik açılır: http://localhost:8501

.streamlit/config.toml Streamlit'i 0.0.0.0 üzerinden tüm LAN'a açar; aynı Wi-Fi'daki telefondan da erişebilirsin.

3) Mobil (opsiyonel)

Flutter WebView shell; Streamlit arayüzünü mobilde gösterir.

cd mobile
flutter pub get
flutter run -d <device_id>

Uygulama ilk açıldığında Ayarlar → Sunucu Adresi'nden bilgisayarının LAN IP'sini gir (örn. http://192.168.1.42:8501). Detaylar için aşağıdaki Telefondan Bağlanma bölümüne bak.

Demo Hesap

Backend ilk açıldığında otomatik oluşur:

Kullanıcı: user1
Şifre:    123456

---

Proje Yapısı

Bütçio/
├── ai-service/        FastAPI + LangChain + Gemini — tüm iş mantığı
│   ├── main.py        REST endpoint'ler (auth, expenses, goals, chat, products)
│   ├── agents/        Orchestrator + tool'lar (chat / product / decision)
│   ├── db.py          SQLite (butcio.db) — kullanıcı, harcama, hedef, gelir
│   └── data/          Mock ürün katalogu + kategoriler
├── streamlit_app/     Web arayüzü (4 sayfa + ana dashboard)
│   ├── app.py         Login + ana sayfa (KPI'lar, sağlık skoru)
│   ├── pages/         Asistan · Ürün Analizi · Finans · Hedefler
│   └── utils.py       API helper'ları + ortak UI
├── mobile/            Flutter WebView shell (Android + iOS)
├── backend/           Spring Boot v2 iskeleti — şu an pasif
└── docs/              Mimari notları, ekran tasarımları

Akış

┌──────────────────┐         ┌──────────────────┐
│  Streamlit UI    │ ──HTTP──▶│  FastAPI (8001)  │
│      8501        │         │  + Gemini + DB    │
└────────┬─────────┘         └──────────────────┘
         │ WebView
┌────────▼─────────┐
│  Flutter Mobil   │
└──────────────────┘

---

Telefondan Bağlanma (LAN üzerinden)

1. PC ve telefon aynı Wi-Fi'da olmalı (cep verisi kapalı).
2. Streamlit'i 0.0.0.0 üzerinden başlat (.streamlit/config.toml ile zaten yapılandırılmış). Manuel:

   python -m streamlit run app.py --server.address=0.0.0.0 --server.port=8501

3. Çıktıda görünen Network URL: http://192.168.X.X:8501 satırındaki IP'yi not al.
4. Windows Firewall: Python'a "Özel ağ" izni ver (popup gelirse "İzin ver"; gelmediyse Windows Defender Güvenlik Duvarı > Uygulamalara izin ver'den Python satırlarında "Özel"i işaretle).
5. Telefonda uygulamayı aç → sağ üst ⚙️ Ayarlar → Sunucu Adresi: http://192.168.X.X:8501 → Kaydet → Geri → Yenile.

Yaygın sorunlar

• "Sunucuya Bağlanılamadı" → 1, 2, 4. adımları sırayla kontrol et.
• Android emülatör kullanıyorsan http://10.0.2.2:8501 (host loopback).
• iOS simulator: http://localhost:8501 yeterli.

---

Modlar

Mod	Kapsam
🧑 Bireysel	Kişisel bütçe, alışveriş kararları, tasarruf hedefleri
👨‍👩‍👧 Aile	Ortak bütçe + aile hedefleri (V2: çok kullanıcılı)
🏢 KOBİ	İşletme gider/gelir takibi (V2: fatura + vergi)

Mod sidebar'dan değiştirilir, DB'ye kaydedilir.

---

Geliştirme

• Sayfalar: streamlit_app/pages/ — Streamlit multipage convention (<sıra>_<Ad>.py)
• Ortak yardımcılar: streamlit_app/utils.py (page_setup, inject_global_css, api_*)
• AI agent'ları: ai-service/agents/ — orchestrator + 3 tool (chat, product, decision)
• DB şeması: ai-service/db.py — SQLite, ilk açılışta auto-migrate

Önemli env değişkenleri (ai-service/.env)

GEMINI_API_KEY=...
GEMINI_MODEL=gemini-2.0-flash-exp  # opsiyonel, varsayılan bu

---

Lisans

BTK Hackathon 2026 — eğitim amaçlı.