Türkçe · English

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.

---

Türkçe

Bu proje nedir?

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.

Öne çıkan özellikler

Ö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

🎥 Demo videosu: YouTube'da izle

Hızlı başlangıç

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 /docs adresinde)

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 sil

GOOGLE_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.

Teknoloji yığı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

Dokümantasyon

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

Proje düzeni

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

---

English

What is this?

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.

Key features

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

🎥 Demo video: Watch on YouTube

Quick start

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 only

Get a GOOGLE_API_KEY free from Google AI Studio. For manual (non-Docker) setup and all make shortcuts, see docs/DEVELOPMENT.md.

Tech stack

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

Documentation

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

Project layout

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