intent_system_design.md

Intent Tabanlı Chatbot Sistem Tasarımı (v1)

Bu doküman, niyet (intent) tespiti, parametre çıkarımı, REST API entegrasyonu, session yönetimi, veri doğrulama ve LLM destekli hibrit karar mekanizmasını içeren chatbot altyapısını detaylı olarak tanımlar.

---

🧠 Amaç

• Kullanıcı ifadelerinden "intent" algılanması
• Parametrelerin (variables) otomatik çıkarılması
• Eksik ya da hatalı parametrelerin sorgulanması
• Format kontrolleri ve validasyon
• Gerekirse REST API çağrıları
• Session bazlı token yönetimi
• Gelen cevabın insani cevaplaşa dönüşü
• Gelişmiş kararlar için hibrit sistem (LLM + logic)

---

📂 JSON Şema (Intent + Data Format)

{
  "data_formats": [
    {
      "name": "currency_format",
      "valid_options": ["dolar", "euro", "TL"],
      "error_message": "Geçerli bir döviz cinsi belirtmelisiniz."
    },
    {
      "name": "client_no_format",
      "pattern": "^[0-9]{6}$",
      "error_message": "Müşteri numaranız 6 haneli olmalıdır."
    }
  ],
  "intents": [
    {
      "name": "doviz-kuru-intent",
      "examples": ["dolar kuru nedir?"],
      "variables": ["currency:{dolar} kuru nedir?"],
      "variable_formats": {
        "currency": "currency_format"
      },
      "action": {
        "url": "https://api.ex.com/doviz",
        "method": "POST",
        "headers": [
          { "key": "Authorization", "value": "Bearer {auth_tokens.doviz-kuru-intent.token}" }
        ],
        "body": {
          "currency": "{variables.currency}"
        },
        "timeout": 5,
        "retry_count": 1,
        "tls": {
          "verify": true,
          "ca_bundle": "/app/certs/my-ca.pem"
        },
        "auth": {
          "auth_endpoint": "https://api.ex.com/auth",
          "auth_body": { "username": "user", "password": "pass" },
          "auth_token_path": "token",
          "auth_refresh_endpoint": "https://api.ex.com/refresh",
          "refresh_body": { "refresh_token": "{session.refresh_token}" }
        },
        "response_parser": {
          "field": "rate",
          "format": "{variables.currency} kuru: {rate} TL"
        },
        "reply_template": "{variables.currency} kuru şu an {rate} TL."
      }
    }
  ]
}

---

🧭 Chat Akışı (Hibrit)

1. Kullanıcıdan mesaj alınır (POST /chat)
2. Session bulunur (X-Session-ID header)
3. Intent tespiti (bert model)
4. Parametreler extract_parameters() ile alınır
5. variable_formats varsa validasyon yapılır
6. Eksik/hatalı varsa awaiting_variable kaydedilir, soru sorulur
7. Tüm parametreler tamamsa:
   • Gerekirse auth token üretilir / yenilenir
   • API çağrısı yapılır
   • response_parser uygulanır
   • reply_template ile mesaj hazır
8. Session güncellenir, cevap döndürülür

---

📦 Session Yapısı

{
  "session_id": "abc-123",
  "variables": {
    "tckn": "12345678900"
  },
  "auth_tokens": {
    "doviz-kuru-intent": {
      "token": "...",
      "refresh_token": "..."
    }
  },
  "awaiting_variable": "currency",
  "last_intent": "doviz-kuru-intent"
}

---

🧩 Placeholder Kullanımı

Amaç	Yazım
Parametre	{variables.currency}
Session verisi	{session.tckn}
Token	{auth_tokens.intent.token}

---

✅ Sonraki Adımlar

• resolve_placeholders() fonksiyonu
• validate_variable_formats()
• auth_token_handler() → create + refresh
• execute_intent() tam mantık
• log() yapısı

---

Bu tasarım, modüler ve üretim ortamı için ölçeklenebilir sağlam bir altyapı sunar.