Karar, BTK Hackathon 2026 için özel olarak geliştirilmiş yapay zekâ tabanlı bir arama (Agentic Search) projesidir. Bir şey satın almadan önce Karar'a sorun; akıllı ajanlarımız güncel fiyatları araştırsın ve kalan bütçenizi anlık olarak kontrol etsin. Analiz sonunda size net bir yönlendirme yapar. Üstelik gelir ve giderlerinizi sisteme tamamen doğal bir Türkçe ile konuşarak da kolayca ekleyebilirsiniz.
Karar is an AI-driven Agentic Search project developed specially for BTK Hackathon 2026. Before making a purchase, just ask Karar. Our smart agents instantly research current prices and check your remaining budget to provide clear, actionable guidance. Plus, you can easily log your income and expenses using natural, conversational Turkish.
Karar, bir şey almadan önce o alışverişin bütçenize uyup uymadığını öğrenmenizi sağlar. Ürünü yazarsınız; yapay zekâ ajanları internette güncel fiyatları araştırır, aylık kalan bütçenizi kontrol eder ve gerekçeli bir karar döndürür. Ajanlar çalışırken adımları takip edebilirsiniz.
Sesle de çalışır: mikrofona dokunun, Türkçe doğal bir şekilde konuşun ("maaşım 50 bin yattı, markete 300 lira harcadım"), uygulama gelir ve gider kayıtlarını çıkarır; siz gözden geçirip onaylarsınız.
| Özellik | Açıklama |
|---|---|
| Satın Alma Danışmanı | Alım sorusu → YEŞİL/SARI/KIRMIZI karar + canlı fiyatlar. Bütçe sorusu → anlık özet yanıtı. Konu dışı sorgular kibarca reddedilir. |
| Canlı ajan adımları | SSE ile her alt ajanın ilerlemesi akar: Soru anlaşılıyor → Ürün araştırılıyor / Bütçe kontrol ediliyor → Karar veriliyor / Bütçe yorumlanıyor. |
| Türkçe sesle giriş | Gelir ve giderlerinizi konuşun; çok kipli bir ajan deşifre eder ve çıkarır. Kaydetmeden önce gözden geçirirsiniz. |
| Gelir & gider takibi | Tam CRUD, aylık özetler, kategori harcaması, günlük toplamlar, ısı haritaları. |
| Sorgu geçmişi | Kaydedilmiş, sabitlenmiş ve trend olan geçmiş sorular, karar özetleriyle. |
| Google Arama temellendirme | Türk e-ticaret sitelerinden gerçek fiyatlar, Google'ın zorunlu arama atıfıyla. |
🎥 Demo videosu: YouTube'da izle
En hızlı yol Docker Compose:
cp .env.example .env # ardından GOOGLE_API_KEY değerini ekle
docker compose up --build- Önyüz → http://localhost:3000
- Arka uç API → http://localhost:8000 (dokümantasyon
/docsadresinde)
Uygulamayı sunum için gerçekçi demo verileriyle doldurmak için:
./seed_demo.sh # yükle (idempotent)
./seed_demo.sh --reset # sil ve yeniden yükle
./seed_demo.sh --clear # yalnızca silGOOGLE_API_KEY anahtarını Google AI Studio
üzerinden ücretsiz alabilirsiniz. Docker'sız manuel kurulum ve tüm make
kısayolları için docs/DEVELOPMENT.md dosyasına bakın.
| Katman | Teknoloji |
|---|---|
| Ajanlar | Google Agent Development Kit (ADK) ≥ 1.33, Gemini 3 (flash / pro) |
| Arka uç | FastAPI, SQLModel, SQLite, Python 3.12+, uv ile yönetilir |
| Önyüz | Next.js 16, React 19, TypeScript, Tailwind CSS 4, shadcn/ui, TanStack Query |
| Araçlar | ruff + mypy (arka uç), eslint + vitest (önyüz), Docker Compose |
| Belge | İçeriği |
|---|---|
| docs/ARCHITECTURE.md | Çok ajanlı tasarım, istek yaşam döngüsü, diyagramlar |
| docs/DEVELOPMENT.md | Yerel kurulum, ortam değişkenleri, Docker, testler, lint |
| docs/API.md | REST + SSE uç nokta referansı |
| docs/FEATURES.md | Özellik özelliğine kullanıcı rehberi |
btk-hackathon-2026/
├── backend/
│ ├── agent/
│ │ ├── sub_agents/ triage, product_search, budget_check,
│ │ │ budget_answer, decision
│ │ ├── tools/ finansal araçlar (bütçe sorgulama)
│ │ ├── purchase_advisor.py ConditionalRouter kök orkestratör
│ │ ├── router.py özel BaseAgent yönlendirme mantığı
│ │ ├── voice_recorder.py çok kipli ses giriş ajanı
│ │ └── schemas.py AdvisorResponse, TriageResult şemaları
│ ├── api/
│ │ ├── routes/ chat, expenses, income, queries,
│ │ │ voice, categories, recommendations
│ │ ├── db/ SQLModel modelleri, göçler
│ │ └── main.py FastAPI uygulama giriş noktası
│ ├── tests/ birim + entegrasyon test takımları
│ └── seed_demo.py demo veri yükleme betiği
├── frontend/
│ ├── app/ Next.js sayfaları (ana, giderler, gelir, geçmiş)
│ ├── components/
│ │ ├── chat/ ajan-adımcı, karar-kartı
│ │ ├── dashboard/ grafikler, son-giderler, ekleme-formları
│ │ ├── expenses/ tablo, ısı-haritası, kategori-çubukları, istatistikler
│ │ ├── history/ sorgu zaman çizelgesi, sabitlenmiş liste, trendler
│ │ ├── income/ gelir tablosu, istatistik paneli
│ │ ├── search/ arama-çubuğu, yanıt-kartı, kaynak-paneli
│ │ ├── shared/ üst-nav, marka-logosu, düzen bileşenleri
│ │ └── voice/ mikrofon-butonu, inceleme-modalı
│ └── lib/ api-client, tipler, araçlar
├── docs/ mimari, API, geliştirme, özellikler
├── docker-compose.yml
├── Makefile sık kullanılan görev kısayolları
├── seed_demo.sh demo veri yükleyici (docker exec üzerinden seed_demo.py)
├── SPEC.md özellik şartnameleri
└── TASKS.md uygulama görev takibi
Karar lets you find out whether something fits your budget before you buy it. Type the product; AI agents search current prices online, check your remaining monthly budget, and return a reasoned verdict. You can follow each step as the agents run.
Voice works too: tap the mic, speak naturally in Turkish ("maaşım 50 bin yattı, markete 300 lira harcadım"), and the app pulls out income and expense entries for you to review and confirm.
| Feature | Description |
|---|---|
| Purchase Advisor | Ask to buy something → GREEN/YELLOW/RED verdict with live web prices. Ask about your budget → snapshot answer. Off-topic queries are declined politely. |
| Live agent steps | SSE streams each sub-agent's progress: Soru anlaşılıyor → Ürün araştırılıyor / Bütçe kontrol ediliyor → Karar veriliyor / Bütçe yorumlanıyor. |
| Turkish voice entry | Speak income & expenses; a multimodal agent transcribes and extracts them. Review before anything is saved. |
| Income & expense tracking | Full CRUD, monthly summaries, category spend, daily totals, heatmaps. |
| Query history | Saved, pinned, and trending past questions with decision summaries. |
| Google Search grounding | Real prices from Turkish e-commerce, with Google's required search attribution. |
🎥 Demo video: Watch on YouTube
The fastest path is Docker Compose:
cp .env.example .env # then add your GOOGLE_API_KEY
docker compose up --build- Frontend → http://localhost:3000
- Backend API → http://localhost:8000 (docs at
/docs)
To populate the app with realistic demo data for a presentation:
./seed_demo.sh # seed (idempotent)
./seed_demo.sh --reset # wipe and re-seed
./seed_demo.sh --clear # wipe onlyGet a GOOGLE_API_KEY free from Google AI Studio.
For manual (non-Docker) setup and all make shortcuts, see docs/DEVELOPMENT.md.
| Layer | Technology |
|---|---|
| Agents | Google Agent Development Kit (ADK) ≥ 1.33, Gemini 3 (flash / pro) |
| Backend | FastAPI, SQLModel, SQLite, Python 3.12+, managed with uv |
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS 4, shadcn/ui, TanStack Query |
| Tooling | ruff + mypy (backend), eslint + vitest (frontend), Docker Compose |
| Doc | What's inside |
|---|---|
| docs/ARCHITECTURE.md | Multi-agent design, request lifecycle, diagrams |
| docs/DEVELOPMENT.md | Local setup, env vars, Docker, tests, linting |
| docs/API.md | REST + SSE endpoint reference |
| docs/FEATURES.md | Feature-by-feature user walkthrough |
btk-hackathon-2026/
├── backend/
│ ├── agent/
│ │ ├── sub_agents/ triage, product_search, budget_check,
│ │ │ budget_answer, decision
│ │ ├── tools/ financial tools (budget lookup)
│ │ ├── purchase_advisor.py ConditionalRouter root orchestrator
│ │ ├── router.py custom BaseAgent routing logic
│ │ ├── voice_recorder.py multimodal voice entry agent
│ │ └── schemas.py AdvisorResponse, TriageResult schemas
│ ├── api/
│ │ ├── routes/ chat, expenses, income, queries,
│ │ │ voice, categories, recommendations
│ │ ├── db/ SQLModel models, migrations
│ │ └── main.py FastAPI app entry point
│ ├── tests/ unit + integration test suites
│ └── seed_demo.py demo data seed script
├── frontend/
│ ├── app/ Next.js pages (home, expenses, income, history)
│ ├── components/
│ │ ├── chat/ agent-stepper, verdict-card
│ │ ├── dashboard/ charts, recent-expenses, add-forms
│ │ ├── expenses/ table, heatmap, category-bars, stats
│ │ ├── history/ query timeline, pinned list, trending
│ │ ├── income/ income table, stats panel
│ │ ├── search/ search-bar, answer-card, sources-panel
│ │ ├── shared/ top-nav, brand-logo, layout primitives
│ │ └── voice/ mic-button, review-modal
│ └── lib/ api-client, types, utils
├── docs/ architecture, API, development, features
├── docker-compose.yml
├── Makefile common task shortcuts
├── seed_demo.sh demo data loader (wraps seed_demo.py via docker exec)
├── SPEC.md feature specifications
└── TASKS.md implementation task tracking