🧮 Calculator Agent

AI Builder Challenge – Broken Calculator Agent Solution

---

📌 Proje Hakkında Genel Bakış

Bu proje, AI Builder Challenge – Broken Calculator Agent hackathonu kapsamında verilen hatalı ve eksik bir yapay zekâ destekli hesap makinesi uygulamasının tamamen düzeltilmesi, iyileştirilmesi ve kullanıcı dostu bir ürüne dönüştürülmesi amacıyla geliştirilmiştir.

Uygulama;

• Komut satırı (CLI) üzerinden çalışan,
• Modüler mimariye sahip,
• Arka planda Gemini API kullanan,
• Birçok matematiksel ve mühendislik alanını kapsayan
  akıllı bir hesap makinesi ajanıdır.

Hackathon süresi boyunca sadece hataları gidermekle kalmayıp aynı zamanda:

• Kullanıcı deneyimi baştan tasarlanmış,
• Arayüz rehberli hale getirilmiş,
• Kod mimarisi sadeleştirilmiş ve genişletilebilir hale getirilmiştir.

---

🎯 Projenin Temel Hedefleri

• 🚨 Sessiz çalışan (silent failure) hataları tespit edip görünür hale getirmek
• ❌ Yanlış yapılandırılmış API kullanımını düzeltmek
• 🧩 Tüm modülleri tek bir merkezden yönetilebilir hale getirmek
• 🎨 Kullanıcıyı yönlendiren, renkli ve örnekli bir arayüz tasarlamak
• 📦 Projeyi hackathon sonrası da geliştirilebilir bir yapıya dönüştürmek

---

✅ Hackathon Sürecinde Yapılan İyileştirmeler

🔧 1. Kod ve Altyapı Hatalarının Giderilmesi

Aşağıdaki kritik problemler düzeltildi:

• ❗ Yanlış Gemini model adı nedeniyle alınan 404 hataları giderildi.

• ❗ Günlük ücretsiz kota dolunca oluşan 429 ResourceExhausted hatası analiz edildi.

• ❗ Hatalı sys.path kullanımından doğan ModuleNotFoundError problemleri çözüldü.

• ❗ google-generativeai ve api_core paketleri arasındaki sürüm uyumsuzlukları giderildi.

• ❗ Tüm hata türleri için özel exception sınıfları yazıldı:

  • InvalidInputError
  • CalculationError
  • SecurityViolationError
  • ModuleNotFoundError
  • GeminiAPIError

Bu sayede kullanıcı artık anlaşılır, yönetilebilir ve loglanabilir hatalar almaktadır.

---

🧠 2. Gemini API Entegrasyonunun Stabil Hale Getirilmesi

• Tüm LLM çağrıları GeminiAgent sınıfında merkezileştirildi.
• Tek noktadan retry mekanizması uygulandı.
• API kotası dolduğunda sistemin tamamen çökmesi engellendi.
• LLM açıklaması alınamadığında uygulama yerel hesaplama ile çalışmaya devam edecek şekilde yeniden düzenlendi.

---

🎨 3. Komut Satırı Arayüzünün Baştan Tasarlanması

Eski sistemde kullanıcı:

• Ne yazacağını bilmiyor,
• Hangi modda olduğunu fark etmiyor,
• Hatalı girişte yönlendirilmeden kalıyordu.

Yeni tasarım ile:

✅ Renkli
✅ Kalın çerçeveli
✅ Rehberli
✅ Konu bazlı
✅ Örnekli

bir kullanıcı deneyimi oluşturuldu.

---

🖥️ Yeni Arayüz Akışı (UI Akışı)

1️⃣ Karşılama Ekranı

Uygulama açıldığında ilk olarak aşağıdakiler gösterilir:

• Proje adı
• Versiyon bilgisi
• Kısa açıklama
• Hızlı kullanım ipuçları

Çıkış: q   |   Konu Değiştir: menu   |   Yardım: help



[1] Temel Matematik
[2] Kalkulus
[3] Lineer Cebir
[4] Denklem Çözme
[5] Grafik Çizme
[6] Finans
[7] İstatistik
[8] Birim Dönüşüm
[9] Sayı Teorisi
[10] Kripto Matematik
[11] Fizik
[12] Mantık / Boolean

!calculus derivative x^2        → x² fonksiyonunun türevi
!calculus integral 2*x         → 2x fonksiyonunun integrali
!calculus limit (...) x->1     → Limit hesabı

Konu değiştir: menu | Yardım: help

src/
├── main.py                     → Ana arayüz ve orchestrator
├── core/
│   ├── agent.py                → Gemini API yöneticisi
│   ├── parser.py               → Kullanıcı komutu ayrıştırma
│   └── validator.py            → Güvenli giriş kontrolü
├── modules/
│   ├── basic_math.py
│   ├── calculus.py
│   ├── linear_algebra.py
│   ├── equation_solver.py
│   ├── graph_plotter.py
│   ├── financial.py
│   ├── statistics.py
│   ├── unit_converter.py
│   ├── conversion.py
│   ├── number_theory.py
│   ├── crypto_math.py
│   ├── physics.py
│   ├── logic.py
│   └── base_module.py
├── utils/
│   ├── logger.py
│   ├── helpers.py
│   └── exceptions.py
└── config/
    └── settings.py
---

🔢 1. Temel Matematik — basic_math.py

Amaç:
Dört işlem, parantezli ifadeler, üs alma ve negatif sayılar gibi temel aritmetik işlemleri güvenli şekilde hesaplamak.

Özellikler:

• Toplama, çıkarma, çarpma, bölme
• Parantezli ifadeler
• Üs alma
• Negatif sayılar
• Hatalı giriş kontrolü (sıfıra bölme vb.)

Örnek Kullanım:

2+3*4
(5+3)/2
-3^2

---

📐 2. Kalkülüs — calculus.py

Amaç:
Türev, integral ve limit işlemlerini sembolik olarak çözmek.

Desteklenen İşlemler:

• Türev alma
• Belirsiz integral alma
• Limit hesaplama

Örnek Kullanım:

!calculus derivative x^2
!calculus integral 2*x
!calculus limit (x^2-1)/(x-1) x->1

---

🧮 3. Lineer Cebir — linear_algebra.py

Amaç:
Matrisler ve lineer denklem sistemleri üzerinde işlem yapmak.

Özellikler:

• Determinant hesaplama
• Matris çarpımı
• Transpoz alma
• Lineer sistem çözümü

Örnek Kullanım:

!linalg determinant [[1,2],[3,4]]
!linalg solve [[1,2],[3,4]] [5,6]

---

✏️ 4. Denklem Çözme — equation_solver.py

Amaç:
Cebirsel denklemleri otomatik olarak çözmek ve köklerini bulmak.

Desteklenenler:

• Birinci dereceden denklemler
• İkinci dereceden denklemler

Örnek Kullanım:

!solve 2x+5=13
!solve x^2-5x+6=0

---

📈 5. Grafik Çizme — graph_plotter.py

Amaç:
Girilen matematiksel fonksiyonların grafiklerini oluşturmak.

Özellikler:

• Parabol, trigonometrik ve üstel fonksiyonlar
• Görsel çıktıyı dosya olarak kaydetme

Örnek Kullanım:

!plot x^2
!plot sin(x)
!plot exp(-x)

---

💰 6. Finans Hesapları — financial.py

Amaç:
Finansal işlemleri otomatik olarak hesaplamak.

İçerik:

• Basit faiz
• Bileşik faiz
• Vade ve getiri hesaplamaları

Örnek Kullanım:

!finance simple_interest 1000 0.12 2
!finance compound_interest 1000 0.10 3

---

📊 7. İstatistik — statistics.py

Amaç:
Veri setleri üzerinde temel istatistiksel işlemler yapmak.

Desteklenenler:

• Ortalama
• Varyans
• Dağılım analizi

Örnek Kullanım:

!stats mean [1,2,3,4,5]
!stats variance [1,2,3,4,5]

---

🔁 8. Birim Dönüşüm — unit_converter.py & conversion.py

Amaç:
Farklı birimler arasında otomatik dönüşüm yapmak.

Desteklenen Birimler:

• Uzunluk (km, m, cm)
• Ağırlık (kg, g)
• Sıcaklık (C, F)

Örnek Kullanım:

!convert 5 km to m
!convert 10 kg to g
!convert 25 C to F

---

🔢 9. Sayı Teorisi — number_theory.py

Amaç:
Tam sayılar üzerinde teorik işlemler yapmak.

İçerik:

• EBOB
• EKOK
• Modüler aritmetik
• Asal sayı kontrolü

Örnek Kullanım:

!nt gcd 24 36
!nt lcm 12 18
!nt mod 17 5

---

🔐 10. Kripto Matematik — crypto_math.py

Amaç:
Kriptografik matematik işlemlerini simüle etmek.

İşlemler:

• Modüler üs alma
• Asal sayı kontrolü

Örnek Kullanım:

!crypto modexp 2 10 7
!crypto isprime 97

---

⚡ 11. Fizik — physics.py

Amaç:
Temel fizik formüllerini otomatik hesaplamak.

İçerik:

• Ohm Kanunu
• Basit hız ve akım hesapları

Örnek Kullanım:

!physics ohm 12V 4ohm
!physics velocity 10m 2s

---

✅ 12. Mantık / Boolean — logic.py

Amaç:
Mantık ifadeleri üzerinde işlem yapmak ve doğruluk analizleri yapmak.

İçerik:

• Mantıksal bağlaçlar (and, or, not)
• Doğruluk analizleri

Örnek Kullanım:

!logic (A and B) or not C
!logic A and (B or C)

---

---

🖼️ Ekran Görüntüleri

🔹 Genel Arayüz Görünümleri

Karşılama Ekranı	Konu Menüsü

---

🔹 Kalkülüs ve Sonuç Ekranları

Kalkülüs Örnekleri	Sonuç Çıktısı

---

🔹 Ek Örnek Çıktılar

Örnek Çıktı	Adım Adım Çözüm & Güven Skoru