hakunamadata-market-opportunity

Cave2Cloud — Mağaradan Pazara Akıllı İhracat Asistanı

Kapadokya Hackathon 2026 projesi. KOBİ ihracatçıları için veri-grounded, karbon-bilinçli, ML-destekli pazar/ürün analiz platformu.

Bu commit Step 1 — Temel İskelet'tir. Sadece Google Vertex AI canlı, diğer tüm modüller stub. TCMB, Nominatim, OpenRouteService, NewsAPI, World Bank vb. dış API'ler bu adımda yoktur.

Önkoşullar

• Python 3.11+
• Node.js 18+
• Aktif bir Google Cloud project'i
• Vertex AI API'si etkinleştirilmiş

Vertex AI Setup

1. GCP Console → APIs & Services → Vertex AI API'sini etkinleştir.
2. IAM & Admin → Service Accounts → yeni bir service account oluştur, "Vertex AI User" rolü ver.
3. Service account için JSON key indir.
4. JSON içinden 3 alanı backend/.env dosyasına kopyala:
   • project_id → VERTEX_PROJECT_ID
   • client_email → VERTEX_CLIENT_EMAIL
   • private_key → VERTEX_PRIVATE_KEY (tek satır; gerçek satır sonları yerine \n kalır)
5. İkinci bir SA varsa fallback olarak VERTEX_PROJECT_ID_2, VERTEX_CLIENT_EMAIL_2, VERTEX_PRIVATE_KEY_2 doldurulabilir.
6. JSON key dosyasını diske bırakma — .env yeterli, gitignore'lı.

Kullanılan modeller (Mayıs 2026)

Gemini 3.x ailesi yalnızca global endpoint'te çalışır (us-central1 404 döner). Kod region routing'i otomatik yapar — gerek yok elle ayarlamana.

SDK: text/vision/image için google-genai (yeni), embedding için vertexai (eski). İkisi de pip install -r requirements.txt ile gelir.

Setup

# 1. Backend env
cp backend/.env.example backend/.env
# backend/.env içine Vertex SA 3 alanını doldur (yukarıdaki Vertex AI Setup adımları).

# 2. Backend
cd backend
python -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# 3. Frontend (yeni terminal)
cd frontend
cp .env.local.example .env.local
npm install
npm run dev

Backend → http://localhost:8000 Frontend → http://localhost:3000

Test Endpoint'leri

Hepsi 200 dönmeli ve gerçek Vertex AI çağrısı yapmalıdır.

curl http://localhost:8000/health
curl http://localhost:8000/vertex/test-text
curl http://localhost:8000/vertex/test-vision
curl http://localhost:8000/vertex/test-embedding
curl http://localhost:8000/vertex/test-image-gen

/vertex/test-image-gen ilk çağrıda Nano Banana Pro'yu dener; hata alırsa otomatik olarak Nano Banana 2 fallback'ine geçer ve cevapta fallback_attempted: true döner.

Repo Yapısı

cave2cloud/
├── backend/              FastAPI + Vertex AI
│   ├── main.py
│   ├── config.py
│   ├── vertex/           Vertex AI istemcileri
│   ├── routes/           API endpoint'leri (çoğu stub)
│   ├── ml/               LightGBM inference (dummy)
│   ├── rag/              ChromaDB iskelet
│   └── data/             PDF, ChromaDB, cultural rules
└── frontend/             Next.js 14 + Tailwind + shadcn/ui
    ├── app/              App Router sayfaları
    ├── components/       UI bileşenleri
    └── lib/              API wrapper, utils

Sonraki Adımlar

• Step 2 — TCMB EVDS widget canlı
• Step 3 — RAG korpusu (13 PDF) ChromaDB ingest
• Step 4 — ML model eğitim (World Bank + UN Comtrade)
• Step 5 — Nominatim + OpenRouteService karbon modülü
• Step 6 — ElevenLabs voice + QR story sayfası