mini-agent

LangChain olmadan, sıfırdan bir tool-calling agent. ~400 satır Python'da: agent loop + decorator-tabanlı tool registry + multi-provider fallback (Gemini → local GGUF).

Herkes AgentExecutor çağırıyor ama altında ne döndüğünü bilmiyor. Bu repo o kara kutuyu açıyor. Bir agent'ın gerçekte ne olduğunu görmek istiyorsan — soyutlama yok, sihir yok doğru yerdesin.

┌─────────────────────────────────────────────────────────┐
│                      AGENT LOOP                            │
│                                                            │
│   kullanıcı  ──►  provider.generate()  ──►  cevap mı?      │
│                          ▲                      │          │
│                          │                      ▼          │
│                   araç sonucu          araç çağrısı mı?    │
│                          ▲                      │          │
│                          └──── registry.execute() ◄────────┘
└─────────────────────────────────────────────────────────┘
            │                              │
            ▼                              ▼
   ┌─────────────────┐          ┌──────────────────────┐
   │  TOOL REGISTRY  │          │   FALLBACK ROUTER     │
   │  @tool decorator│          │  Gemini ──► Gemini    │
   │  Pydantic schema│          │     ──► Local (GGUF)  │
   └─────────────────┘          └──────────────────────┘

Neden LangChain yok?

Eğitim amaçlı. LangChain harika bir kütüphane ama bir agent'ın mekaniğini öğrenmek için kötü bir başlangıç çok fazla soyutlama gerçekte olan biteni gizliyor. Burada gördüğün her satır senin kontrolünde. Öğrendikten sonra istersen LangChain'e geç; ama önce temeli gör.

Mimari — 4 katman

Katman	Dosya	Ne yapar
Agent loop	agent.py	observe → think → act → observe döngüsü. Sonsuz döngü koruması. ~80 satır.
Tool registry	tools.py	@tool decorator fonksiyon imzasından otomatik Pydantic + JSON Schema üretir.
Provider katmanı	providers.py	Provider protocol'ü; Gemini (native function calling) + local GGUF (offline).
Fallback router	providers.py	Provider'ları sırayla dener; biri patlarsa bir sonrakine düşer.

Kurulum

git clone https://github.com/esephaneli/mini-agent.git
cd mini-agent
uv sync                      # temel (Gemini)
uv sync --extra local        # + offline GGUF fallback istiyorsan
export GEMINI_API_KEY="..."  # https://aistudio.google.com/apikey

Hızlı başlangıç

from mini_agent import Agent, GeminiProvider, build_default_registry

agent = Agent(GeminiProvider(), build_default_registry())
result = agent.run("100 dolar kaç TL eder?")
print(result.answer)

Kendi aracını eklemek sadece bir fonksiyon yaz:

from mini_agent import tool, build_default_registry, Agent, GeminiProvider

@tool
def kdv_dahil(tutar: float, oran: float = 20.0) -> str:
    """Bir tutara KDV ekler."""
    return f"{tutar * (1 + oran/100):.2f} TL"

reg = build_default_registry()
reg.register(kdv_dahil)
Agent(GeminiProvider(), reg).run("1500 TL'ye %20 KDV ekle")

Schema'yı elle yazmana gerek yok — @tool decorator type hint'lerden üretiyor.

Multi-layer fallback

from mini_agent import FallbackRouter, GeminiProvider, LocalProvider, Agent, build_default_registry

router = FallbackRouter([
    GeminiProvider("gemini-2.5-flash"),       # birincil
    GeminiProvider("gemini-2.5-flash-lite"),  # rate-limit yerse
    LocalProvider("model.gguf"),              # tamamen offline son çare
])
agent = Agent(router, build_default_registry())

Birincil model rate-limit yer ya da ölürse, router otomatik bir sonrakine geçer. Local katman internetsiz çalışır — gerçek dayanıklılık (resilience) burada.

Örnekler

uv run python examples/01_basic.py       # tek tur, hazır araçlar
uv run python examples/02_multi_tool.py  # kendi aracını ekle
uv run python examples/03_fallback.py    # provider düşürme demosu

Test

uv run pytest        # API key GEREKMEZ — sahte provider ile loop'u test eder

Hazır araçlar

hesapla (güvenli, eval yok), bugun, doviz_kuru (TCMB canlı kuru).

---

Pitfalls — dürüst notlar

Production'a taşımadan önce bilmen gerekenler:

1. Gemini function-calling formatı OpenAI'dan farklı. function_call / function_response part'ları ayrı; OpenAI'nin tool_calls dizisi gibi değil. providers.py içindeki çeviri katmanına bak.
2. Validation şart. Model bazen eksik veya yanlış tipte argüman gönderir. Registry bunu yakalayıp modele "hata" olarak geri besliyor (crash etmiyor) ki model kendini düzeltsin.
3. Sonsuz döngü riski gerçek. max_iterations olmadan model araç çağırıp durabilir. Guard her zaman açık.
4. Küçük local modeller tool-calling'i kötü yapar. 3B-7B quantized modeller native function-calling'i güvenilir yapamaz; LocalProvider bu yüzden JSON-prompt yöntemi kullanıyor — kırılgan ama offline garantisi veriyor. 6GB VRAM için Qwen2.5-3B-Instruct Q4_K_M gibi küçük bir model seç.
5. eval kullanma. hesapla aracı AST ile sınırlı operatör değerlendirmesi yapıyor; eval bir RCE açığıdır.

Lisans

MIT.