Upload 2 files

flare-tasarim.md

@@ -0,0 +1,379 @@
+Güncellenmiş flare-tasarim.md
+markdown# 🏗 Genel Mimari
+
+Flare, Spark LLM motorunun üstünde çalışan, çok adımlı ve akıllı bir orchestration katmanıdır. Görevleri:
+
+✅ Kullanıcıdan gelen mesajları Spark kullanarak sohbet halinde sürdürmek,
+✅ Spark ile, kullanıcı mesajından intent ve parametre extraction akışını yönetmek,
+✅ Eksik parametre değerleri için system prompt oluşturup, Spark ile insani mesaja dönüştürerek bu parametrelerin değerlerini kullanıcıya tamamlatmak,
+✅ Doğru parameter değerleri ile API çağrıları yapmak,
+✅ API cevabını Spark üzerinden insanileştirilmiş metne dönüştürmek ve kullanıcıya iletmek,
+✅ Her şeyi session bazında, state machine mantığında takip etmek.
+
+Bu yapı Parloa gibi sistemlerde kullanılan "flow engine + LLM + tool orchestration" yaklaşımına dayanır.
+
+# Spark Entegrasyonu
+
+Spark servisinin base url'i service_config.jsonc dosyasında config.spark_endpoint olarak tanımlanmıştır.
+
+Spark'a gönderilecek tüm request'lerde header'a Authorization: Bearer <SPARK_TOKEN> eklenmelidir. SPARK_TOKEN, .env dosyasında tanımlıdır.
+
+# Internal Prompt Mekanizması
+
+Flare servisi, tüm Spark isteklerinde kullanılmak üzere merkezi bir internal_prompt tanımına sahiptir. Bu prompt, service_config.jsonc dosyasında config.internal_prompt olarak saklanır ve her intent detection işleminde project version'daki general_prompt'un başına otomatik olarak eklenir.
+
+Internal prompt, Spark'ın tutarlı davranış sergilemesi için gerekli temel kuralları içerir:
+- Intent detection formatı ve kuralları  
+- Dil ayarları (<project language> placeholder'ı ile)
+- Intent isimleri ve caption'ları (<intent names> ve <intent captions> placeholder'ları ile)
+- Selamlama ve small talk davranışları
+- Güvenlik kuralları
+
+Bu mekanizma sayesinde tüm projeler arasında tutarlı bir Spark davranışı sağlanır. Internal prompt içindeki placeholder'lar runtime'da gerçek değerlerle değiştirilir:
+- <intent names>: Proje versiyonu içinde tanımlı intentlerin name'leri, tırnak içinde ve virgülle ayrılmış şekilde
+- <intent captions>: Proje versiyonu içinde tanımlı intentlerin caption'ları, tırnak içinde ve virgülle ayrılmış şekilde  
+- <project language>: Projenin default_language alanından alınan dil (Turkish, English, German, vb.)
+
+# Startup
+
+Flare servisi ayağa kalktıktan sonra ilk iş olarak service_config.jsonc dosyasında tanımlı enabled=true olan her bir project için, projenin published=true olan en büyük id'ye sahip versiyonundaki bilgilerle ve dosyadaki config nesnesi altındaki work_mode ve cloud_token bilgisi ile birlikte, spark_endpoint url'indeki Spark servisine bir /startup request'i gönderir.
+
+Bu request'in body formatı şu şekilde:
+
+```json
+{
+  "work_mode": "<config.work_mode>",
+  "cloud_token": "<config.cloud_token>",
+  "project_name": "<project.name>",
+  "project_version": <project.version.id>,
+  "repo_id": "<project.version.llm.repo_id>",
+  "generation_config": <project.version.llm.generation_config>,
+  "use_fine_tune": <project.version.llm.use_fine_tune>,
+  "fine_tune_zip": "<project.version.llm.fine_tune_zip>"
+}
+Başarılı response örneği:
+json{ "message": "✅ project1 versiyon 1 yükleniyor (arka planda)." }
+Başarısız response örneği:
+json{ "error": "<error mesajı>" }
+Chat
+Chat request'lerini Spark'ın /generate endpoint'ine gönderiyoruz. Json request format şu şekilde:
+json{
+  "project_name": "project1",
+  "system_prompt": "you are an helpful virtual assistant. answer the questions of the user with a formal manner.",
+  "user_input": "en ekşi meyve nedir?",
+  "context": [
+    { "role": "user", "content": "Merhaba!" },
+    { "role": "assistant", "content": "Merhaba, nasıl yardımcı olabilirim?" }
+  ]
+}
+Response format:
+json{
+  "model_answer": "En ekşi meyve..."
+}
+🧠 İş Akışı
+Sohbet için bir session ve state takibi yapılacağından, Flare'e öncelikle, request body'de project_name bilgisi içeren bir /start_session request'i gönderilir.
+Flare unique bir session_id üretir ve bir session objesi yaratıp, session_id üzerinden indekslenmiş olan session dictionary'sine ekler ve response'ta session_id değerini döndürür. Session objesi içinde, gönderilen project_name'e karşılık gelen proje bilgileri (id, name, caption) ve proje tanımı altındaki versions array'indeki published=true olan version'lardan en büyük id'ye sahip olanın altındaki bilgileri (llm nesnesi hariç) alıp session nesnesine set eder. Oluşturduğu session'ın işleyişinde bundan sonra bu bilgileri kullanır.
+Session nesnesi içinde ayrıca sohbetin context'ini takip edeceği chat_history array'i ve intent tespit etmesi durumunda, tespit ettiği intent, extract edilen parametreler ve eksik parametreleri takip edeceği property'ler, session state gibi sohbet akışında ihtiyaç duyacağı bilgileri tutar.
+Ardından Flare'e bu session ile gönderilen tüm request'lerin header'ında X-Session-ID key içinde session_id değeri gönderilir.
+Flare, kendisine gelen /chat request'lerini işletirken header'daki X-Session-ID değerini alır (yoksa hata döndürür) ve gönderilen session_id ile session dictionary'sinden ilgili session nesnesini bulur, sohbeti işletmek için session nesnesindeki değerleri kullanır.
+Sohbet sırasında user_input bilgisi, session_id header'ıyla Flare'in /chat endpoint'ine gönderilir.
+1️⃣ Intent Detection
+Kullanıcı mesajı alınır.
+Spark LLM'e, kullanıcı mesajı, session'da tutulan sohbet tarihçesi ve session'da tutulan project version nesnesindeki intent tanımları birleştirilerek (detection_prompt ve intent detection'ı kolaylaştırma amaçlı örnek cümleler içeren examples kısmı) bir system prompt halinde gönderilir.
+Eğer kullanıcının söyledikleri bir intent içermiyorsa, Spark kullanıcıyla normal sohbet eder.
+Spark eğer intent belirlerse, parametreleri bu aşamada extract etmez. Bulduğu intent'in adını özel bir formatta döndürür. Örnek: #DETECTED_INTENT:search_flight_intent
+2️⃣ Parametre Extraction
+Belirlenen intent'e göre beklenen parametre listesi çıkarılır.
+Spark'a, user_input ile birlikte parametre extraction_prompt'ları birleştirilip tek bir system prompt olarak gönderilir. Spark buradan parametre değerlerini extract eder ve özel bir formatta döndürür. Örnek:
+#PARAMETERS:{ "extracted": [ { "to_city": "İstanbul" } ], "missing": [ "to_city", "date"] }
+Döndürülen parametreler tanımdaki variable_name key'i ile session'a eklenir. Eğer birden fazla intent'te aynı variable_name'e sahip parametreler varsa, aynı değişken değerini paylaşırlar.
+3️⃣ Eksik Parametre Tamamlama
+Zorunlu parametrelerden eksik olanlar varsa, Flare bunları kullanıcıdan istemek için uygun prompt'u hazırlar ve Spark'a gönderir. Bunun için, eksik parametrelerin tanımlarındaki name ve intent.parameters.extraction_prompt'lar birleştirilerek tek bir system prompt haline getirilir.
+Spark, kullanıcı cevabını işleyip tekrar extraction yapar ve yukarıdaki #PARAMETERS formatında Flare'e dönüş yapar. Eksik parametre değeri kalmayan kadar Flare-Spark iletişimi bu şekilde döner.
+Sohbette bir intent tespit edildiğinde, bu intent'in zorunlu bir parametresinin variable_name'i session'da zaten mevcutsa ve değer içeriyorsa, bu parametre tekrar extract edilmeye çalışılmaz, session'daki ilgili variable'dan alınıp kullanılır.
+4️⃣ Parametre Validation
+Alınan her parameter değeri, parameter tanımındaki tip ve regex (min/max uzunluk gibi) kurallarla doğrulanır.
+Hatalı değerler varsa, bu parametrelerin invalid_prompt'ları birleştirilip Spark'a tek bir system prompt olarak gönderilir ve Spark kullanıcıya doğrudan döndürülecek insani hata mesajını oluşturup döndürür. Örnek: "Söylediğiniz uçuş numarası hatalı. Uçuş numaranız 6 haneli bir numara olmalıdır."
+5️⃣ API Çağrısı
+Tüm parametreler tamamlanınca Flare, intent'e bağlı API çağrısını yapar.
+Intent'e bağlı API adı, service_config.json'da ilgili intent nesnesinin action alanında tanımlıdır. Bu adı kullanarak apis altındaki ilgili api tanımına ulaşılabilir.
+Bu aşamada kritik bir detay:
+🔑 Eğer API tanımında auth bölümü varsa,
+
+Api çağırılmadan önce, session içinde auth_tokens[api_name] var mı control edilir. Varsa bu token kullanılır.
+Eğer yoksa, token alma işlemi yapılır.
+Token almak için, token_endpoint ve body_template kullanılarak token api servisine request gönderilir, dönen json response içinden response_token_path json path'i kullanılarak token değeri alınır.
+Alınan token session içinde auth_tokens[api_name] olarak saklanır.
+Token expire ederse, token_refresh_endpoint ve token_refresh_body kullanılarak mevcut token refresh edilir.
+Header ve body'lerdeki {auth_tokens.api_name.token} placeholder'ları bu token ile doldurulur.
+Eğer auth tanımı yoksa, API çağrısı doğrudan yapılır.
+
+Bu mekanizma API erişiminde güvenlik ve süreklilik sağlar.
+6️⃣ Response Mapping
+API'den dönen JSON response'tan belirli değerleri session değişkenlerine aktarma mekanizmasıdır. Her API tanımında response_mappings array'i ile tanımlanır:
+json"response_mappings": [
+  {
+    "variable_name": "booking_id",
+    "type": "str",
+    "json_path": "booking.confirmation_number"
+  },
+  {
+    "variable_name": "departure_time", 
+    "type": "date",
+    "json_path": "flight_details.departure.time"
+  }
+]
+Bu mapping'ler API başarılı response döndüğünde (status 200) otomatik olarak işlenir. Belirtilen json_path'teki değerler, tanımlanan type'a göre dönüştürülüp session.variables içine variable_name ile kaydedilir.
+Desteklenen type'lar: str, int, float, bool, date
+Bu mekanizma sayesinde API response'larından alınan değerler, sonraki intent'lerde veya API çağrılarında kullanılabilir hale gelir.
+7️⃣ API Cevabını İnsanileştirme
+Api'den dönen ham json, api tanımı altındaki response_prompt ile birlikte Spark'a gönderilir ve akıcı, insani bir cevap üretilir.
+Not: Api tanımındaki response_prompt içindeki {{api_response}} değeri, api'den dönen json string ile replace edilir.
+Örnek: "response_prompt": "Aşağıdaki JSON döviz kuru bilgilerini içeriyor. Kullanıcıya anlaşılır bir Türkçe özet hazırla:\n\n{{api_response}}"
+8️⃣ Session ve State Takibi
+Her kullanıcı sohbeti bir session ID ile takip edilir.
+Session üzerinde:
+
+Son 10 adet konuşma tarihçesi,
+Son intent,
+Toplanan parametreler,
+Eksik parametreler,
+Akışın neresinde olduğumuz (intent detection, parameter extraction, api call, response humanization)
+Api token'ları
+tutulur.
+
+Bu, çok adımlı akışlarda state kaybını engeller.
+Date Type Desteği
+Parametre tanımlarında "date" type'ı desteklenmektedir. Date parametreleri:
+
+ISO format (YYYY-MM-DD) olarak saklanır
+Türkçe tarih ifadeleri otomatik olarak parse edilir (bugün, yarın, 15 Temmuz, vb.)
+Extraction prompt'larında güncel tarih context'i sağlanır
+Validation sırasında geçerli tarih formatı kontrolü yapılır
+
+🏗 Mimari Bileşenler
+BileşenGörevSpark LLMIntent tespiti, parametre extraction, eksik tamamlama ve humanizationFlare Session ManagerHer kullanıcı için session ve state takibiFlare Prompt EngineHer aşamada Spark'a gönderilecek uygun system prompt'u dinamik hazırlayan yapıAPI ConnectorTanımlı API'lere parametrelerle çağrı yapan, auth/refresh yöneten katmanValidation EngineParametre değerlerini tip ve format bazlı doğrulayan yapıUI ve Config KatmanıFlare işleyiş konfigürasyonu ve api tanımları; version bazlı project tanımlamaları; project tanımı altında intent tanımları; intent tanımı altında parametre tanımlarını yöneten arayüz
+📋 Yapılacaklar
+✅ Spark ile intent tespiti için system prompt tasarımı → Örnek cümlelerle zenginleştirme
+✅ Parametre extraction için intent bazlı prompt şablonları hazırlanması
+✅ Eksik parametre tamamlama için eksik parametre bazlı prompt oluşturma
+✅ Parametre tip tanımları ve validation engine geliştirilmesi
+✅ API connector modülü → auth, refresh, token yönetimi, timeout, retry mantığı ile geliştirme
+✅ Humanization prompt'larının API cevabına göre dinamik hazırlanması
+✅ Session ve state machine geliştirme
+✅ Response mapping mekanizması
+✅ Internal prompt sistemi
+✅ Date type desteği
+🔑 Önemli Notlar (Unutulmaması Gerekenler)
+
+LLM prompt'ları tek seferde şişirilmemeli; sohbetin her aşamasında sadece gereken system prompt dinamik oluşturulup gönderilmeli.
+Parametre extraction'da ek bir model (BERT vb.) yerine sadece Spark kullanılacak.
+Intent başına (proje başına max ~8-10 intent), her bir intent için max ~5-6 örnek cümle şeklinde bir kapasite planlaması düşünülebilir.
+Parametre tip ve regex validation başarısızsa, Spark üzerinden insani bir hata mesajı oluşturulup kullanıcıya döndürülmeli,
+API response'larının insanileştirilmesi, kullanıcıya daha iyi bir deneyim sunmak için Spark'tan geçmeli.
+API token yönetimi ve refresh mekanizması, Flare içinde güvenli ve izlenebilir şekilde tutulmalı.
+
+Servis Konfigürasyonu
+Flare'in tanımlarını tutan bir document database gibi kullanacağımız service_config.jsonc dosyasının yapısı, örnek data ve alan açıklamaları ile birlikte aşağıdadır.
+jsonc{
+  // =====================================================
+  // FLARE GLOBAL CONFIGURATION
+  // =====================================================
+  "config": {
+    "work_mode": "hfcloud", // "hfcloud" | "cloud" | "on-premise"
+    "cloud_token": "<your cloud token>", // eğer workmode hfcloud ya da cloud ise zorunlu, on-premise'de kullanılmayacak.
+    "spark_endpoint": "https://ucsturkey-spark.hf.space", // Spark servisine erişim için kullanılacak url
+    "internal_prompt": "⚠️ **NEVER output \"#DETECTED_INTENT:\"...", // Merkezi Spark kuralları
+    "project_id_counter": 1, // Yeni proje ID'leri için counter
+    "last_update_date": "2025-06-08T12:00:00.000Z", // Race condition kontrolü için
+    "last_update_user": "admin",
+    
+    // === Login Users (bcrypt hash + salt): Flare UI kullanılabilecek user'lar ==============
+    "users": [
+      {
+        "username": "admin",
+        "password_hash": "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918",
+        "salt": "random_salt_string"
+      }
+    ]
+  },
+
+  // =====================================================
+  // PROJECTS: Her bir proje bir virtual agent'ı tanımlar
+  // =====================================================
+  "projects": [
+    {
+      "id": 1,
+      "name": "coronos_assistant", // Virtual agent adı
+      "caption": "Coronos Sanal Asistan",
+      "icon": "folder", // Material icon adı
+      "description": "Coronos müşteri hizmetleri asistanı", // Proje açıklaması
+      "enabled": true, // Kullanımda olma durumu
+      "default_language": "tr", // Varsayılan dil kodu
+      "supported_languages": ["tr", "en"], // Desteklenen diller
+      "timezone": "Europe/Istanbul", // Saat dilimi
+      "region": "tr-TR", // Bölge kodu
+      "last_version_number": 1, // Projelerin version_number için versiyon counter. Artarak ilerler.
+      "last_update_date": "2025-06-08T12:00:00.000Z",
+      "last_update_user": "admin",
+      "deleted": false,
+      "created_date": "2025-06-08T12:00:00.000Z",
+      "created_by": "admin",
+
+      // --------------------------------------------------------
+      // VERSIONS: Proje revizyonları ayrı bir version_number ile takip edilir.
+      // Yayınlanmış versiyonlar üzerinde düzenleme yapılamaz.
+      // Yeni versiyon oluşturumak için published versiyonlardan biri seçilir ve kopyası oluştulur, bu kopya üzerinde düzenleme yapılabilir.
+      // --------------------------------------------------------
+      "versions": [
+        {
+          "id": 1, // Proje versiyonu
+          "caption": "v1",
+          "published": true, // Versiyonun yayınlanma durumu.
+          
+          // === Virtual agent'ın yapabileceği işleri tarifler =========
+          "general_prompt": "You are an airline assistant. You can book tickets, give information about booked tickets ...",
+          
+          // === LLM configuration =======================
+          "llm": {
+            "repo_id": "ytu-ce-cosmos/Turkish-Llama-8b-DPO-v0.1", // eğer workmode hfcloud ve cloud ise, kullanılacak llm'in repo id'si. Eğer on-premise ise, llm'in indirileceği url ya da llm'in indirilmeden kullanılacağı network folder path
+            "generation_config": { // Llm'in kullanımı için gerekli konfigürasyon parametreleri
+              "max_new_tokens": 128,
+              "temperature": 0.3,
+              "top_p": 0.7,
+              "repetition_penalty": 1.1
+            },
+            "use_fine_tune": false, // LoRA fine-tune model kullanılma durumu
+            "fine_tune_zip": "" // use_fine_tune: true ise, kullanılacak LoRA adapter zip'in indirleceği url, ya da network file path.
+          },
+          
+          // === INTENTS =================================
+          "intents": [
+            {
+              "name": "currency_rate_intent", // alt çizgi, tire yok
+              "caption": "Kur sorgulama",
+              "locale": "tr-TR",
+              "dependencies": [], // intent bağımlılıkları.
+              
+              // Intent detection
+              "examples": [
+                "What is the dollar rate?",
+                "How much is the euro?"
+              ],
+              "detection_prompt": "Identify if user is asking for currency rate information.", // Intent detection için kullanılacak system prompt.
+              
+              // Parameters: Intent tespit edildiğinde, kullanıcının ifadesinden extract edilecek parametreler
+              "parameters": [
+                {
+                  "name": "currency",
+                  "caption": "Döviz cinsi", // Eksik parametreyi tamamlarken kullanıcıya söylenebilecek parametre adı
+                  "type": "str", // "str" | "int" | "float" | "bool" | "date"
+                  "required": true,
+                  "variable_name": "currency", // Parametre değerini set edeceğimiz session değişkeni adı
+                  "extraction_prompt": "Extract the currency code (USD, EUR, TRY) from the user message.", // Parametre extraction için kullanılacak system prompt
+                  "validation_regex": "^(USD|EUR|TRY)$", // kullanıcıdan alınan parametre değerini validate etmek için kullanılacak regex. Opsiyonel.
+                  "invalid_prompt": "Geçersiz para birimi girdiniz. USD, EUR veya TRY şeklinde giriniz.", // Parametre değeri invalid ise kullanıcıya söylenecek mesajı oluşturacak system prompt
+                  "type_error_prompt": "Para birimi metin olmalıdır (ör: USD)." // Eğer parametre tipi hatalıysa kullanıcıya söylenecek mesajı oluşturacak system prompt
+                }
+              ],
+              
+              // API to call
+              "action": "currency_api", // Bu intent tespit edilip, parametreleri tamamlandığında çağırılacak api'nin adı.
+              
+              // Fallbacks
+              "fallback_timeout_prompt": "Kur servisinde gecikme yaşanıyor. Lütfen biraz sonra tekrar deneyin.", // Api timeout durumunda kullanıcıya söylenecek mesajı oluşturacak system prompt
+              "fallback_error_prompt": "Kur bilgileri alınırken bir hata oluştu, daha sonra tekrar deneyebilir misiniz?" // Api hatası durumunda kullanıcıya söylenecek mesajı oluşturacak system prompt
+            }
+            // ... başka intent'ler
+          ],
+          
+          "last_update_date": "2025-06-08T12:00:00.000Z",
+          "last_update_user": "admin",
+          "deleted": false,
+          "created_date": "2025-06-08T12:00:00.000Z",
+          "created_by": "admin",
+          "publish_date": "2025-06-08T12:00:00.000Z",
+          "published_by": "admin"
+        }
+        // ... yeni versiyonlar
+      ]
+    }
+    // ... başka projeler
+  ],
+
+  // =====================================================
+  // API DEFINITIONS (dict by name): Intent'lerde action olarak kullanılacak api tanımları
+  // =====================================================
+  "apis": [
+    {
+      "name": "currency_api",
+      "url": "https://mock.api/currency",
+      "method": "POST",
+      
+      // Headers as dict; placeholders destekler
+      "headers": {
+        "Content-Type": "application/json",
+        "Authorization": "Bearer {{auth_tokens.currency_api.token}}"
+      },
+      
+      // Body template
+      "body_template": {
+        "currency": "{{variables.currency}}"
+      },
+      
+      // Timeout & retry
+      "timeout_seconds": 5,
+      "retry": {
+        "retry_count": 3,
+        "backoff_seconds": 2,
+        "strategy": "static" // "static" | "exponential"
+      },
+      
+      // Auth (optional)
+      "auth": {
+        "enabled": false,
+        "token_endpoint": "https://mock.api/auth",
+        "token_request_body": {},
+        "response_token_path": "token", // json-path style. Ex: xx.yy.z
+        "token_refresh_endpoint": null, // opsiyonel
+        "token_refresh_body": {} // token_refresh_endpoint varsa zorunlu, yoksa opsiyonel.
+      },
+      
+      "proxy": "", // Proxy (optional)
+      
+      // API response → human-friendly answer
+      "response_prompt": "Aşağıdaki JSON döviz kuru bilgilerini içeriyor. Kullanıcıya anlaşılır bir Türkçe özet hazırla:\n\n{{api_response}}",
+      
+      // Response mapping
+      "response_mappings": [
+        {
+          "variable_name": "exchange_rate",
+          "type": "float",
+          "json_path": "data.rate"
+        }
+      ],
+      
+      "last_update_date": "2025-06-08T12:00:00.000Z",
+      "last_update_user": "admin",
+      "deleted": false,
+      "created_date": "2025-06-08T12:00:00.000Z",
+      "created_by": "admin"
+    }
+  ],
+
+  // =====================================================
+  // ACTIVITY LOG
+  // =====================================================
+  "activity_log": [
+    {
+      "id": 1,
+      "timestamp": "2025-06-08T12:00:00.000Z",
+      "user": "admin",
+      "action": "CREATE_PROJECT",
+      "entity_type": "project",
+      "entity_id": 1,
+      "entity_name": "airline_agent",
+      "details": "Created new project"
+    }
+  ]
+}

flare-ui-tasarim.md

@@ -0,0 +1,516 @@
+## Güncellenmiş flare-ui-2.0.md
+
+```markdown
+# Flare Administration UI - Tasarım Dokümanı
+
+## 📌 Amaç
+
+Flare Administration UI (Flare Admin), kullanıcıların Flare platformunda proje tanımlayıp yönetebileceği bir web arayüzüdür. Angular ile geliştirilir, backend olarak Python ile geliştirilmiş olan Flare backend'i kullanır.
+
+Flare Admin ekranlarında; proje tanımlama, mevcut projeyi düzenleme, projeye versiyon çıkarma, versiyonu publish etme, projeyi enable-disable etme, proje tanımını silme gibi işlemler yapılabilir.
+
+Document database olarak Flare'in service_config.jsonc dosyasını kullanır. Tüm tanım, düzenleme, silme ve listeleme işlemlerini bu dosya üzerinde yapar.
+
+Flare Admin, Flare backend servisi üzerinden Spark ile entegre çalışır.
+
+## Genel Kurallar
+
+Flare Admin, login ekranıyla başlar. Kullanıcı login olduktan sonra tanım ekranları görüntülenir.
+
+Tanım ekranları, tab window'lar şeklinde gruplandırılmıştır. Her tab'da birbiriyle alakalı işlemler yapılır.
+
+Tüm hatalı işlemler, işlemin yapıldığı ekranın alt kısmında kırmızı font ile uyarı şeklinde görüntülenir ve uyarı 5 sn sonra kaybolur.
+
+Boolean alanlar ekranda (hem input olarak, hem de tablo üzerinde) checkbox olarak görüntülenir.
+
+Silme işlemleri öncesinde, silinecek nesnenin diğer nesneler altında kullanımda olup olmadığı kontrol edilir. Eğer kullanımdaysa, silinmesine izin verilmez ve hangi nesneler tarafından kullanıldığını içeren bir mesaj ve hata kodu ile döndürülür. Kullanımda olmayan nesneyi silme öncesinde açılacak bir dialog'da kullanıcıdan onay alınır. Onayın ardından silme işlemi yapılır.
+
+Nesnenin **deleted** alanı varsa silme işlemi fiziksel olarak yapılmaz, deleted=true olarak değiştirilir.
+
+Ortam çok kullanıcılı olduğundan kayıt düzenleme işlemlerinde race condition kontrolü yapılır. Bunun için service_config.jsonc içinde config, project, version ve api nesnelerine **last_update_date** alanı eklenir.
+
+Kullanıcı, düzenlemek için nesneyi ekrana yüklediğinde nesne içindeki bu değeri de yükler. Save butonuna bastığında backend'e bu değeri de gönderir ve backend kayıt öncesi bu değerin service_config.jsonc'deki ilgili nesnedeki değerle aynı olup olmadığını kontrol eder, aynı ise kaydı yapar ve kaydederken bu değeri o andaki tarih-saat-dakika-saniye-milisaniye değeri ile günceller.
+
+Eğer bir başka kullanıcı aynı kaydı düzenliyorsa ve ilk kullanıcıdan sonra save'e bastıysa dosyadaki bu değer değişmiş olacağından backend kayda izin vermez ve "Kayıt başka kullanıcı tarafından düzenlendi. Lütfen tekrar yükleyin." tarzı bir uyarı ile birlikte bir hata kodu döndürür.
+
+Bir diğer durum da, kullanıcı tarafından düzenlenen kaydın, bu kullanıcı kaydetmeden önce başka bir kullanıcı tarafından silinmiş olması durumudur. Backend kayıt öncesi dosyada bu nesneyi bulamazsa "Kayıt başka kullanıcı tarafından silindi." gibi bir uyarı ve bir hata kodu döndürür, kayda izin vermez.
+
+## Auto-save ve Undo/Redo Mekanizması
+
+- Published olmayan version'lar üzerinde çalışırken her 30 saniyede bir otomatik draft kayıt yapılır
+- Son 10 işlem için undo/redo desteği (Ctrl+Z / Ctrl+Y)
+- Draft kayıtlar drafts/ klasöründe tutulur ve UI açıldığında "Recover unsaved changes?" dialog'u gösterilir
+
+## Klavye Kısayolları
+
+- Ctrl+S: Save
+- Ctrl+N: New (context'e göre project/version/intent)
+- Ctrl+F: Search/Filter
+- Ctrl+D: Duplicate
+- Esc: Cancel/Close dialog
+
+## Flare Backend Düzenlemeleri
+
+Flare backend'de Flare Admin UI işleyişi için bazı eklemeler yapılması gerekiyor.
+
+### Eklenecek endpoint'ler:
+
+#### Temel CRUD Endpoint'leri
+
+- POST /api/login - Kullanıcı girişi ve token üretimi
+- GET /api/environment - Environment bilgileri alma
+- PUT /api/environment - Environment bilgilerini kaydetme
+- GET /api/projects - Proje listeleme (pagination, filter, sort destekli)
+- POST /api/projects - Yeni proje oluşturma: Yeni proje oluşturulduğunda backend, version_id_counter alanını **1**'e ayarlar ve otomatik **Version 1** kaydını ekler. Frontend ekstra çağrı yapmaz.
+- PUT /api/projects/{id} - Mevcut projeyi düzenleme
+- DELETE /api/projects/{id} - Mevcut projeyi silme
+- PATCH /api/projects/{id}/toggle - Proje enable/disable
+- POST /api/projects/{id}/versions - Proje versiyonu oluşturma
+- DELETE /api/projects/{id}/versions/{version_id} - Versiyon silme
+- PUT /api/projects/{id}/versions/{version_id} - Versiyon düzenleme
+- POST /api/projects/{id}/versions/{version_id}/publish - Versiyon yayınlama
+- GET /api/apis - API listeleme
+- POST /api/apis - Yeni API ekleme
+- PUT /api/apis/{name} - Mevcut API'yi düzenleme
+- DELETE /api/apis/{name} - Mevcut API'yi silme
+
+#### Spark Integration Endpoint'leri (Yeni)
+
+- POST /api/spark/startup - Projeyi Spark'a yükle
+- GET /api/spark/projects - Spark proje listesi
+- POST /api/spark/project/enable - Projeyi aktifleştir
+- POST /api/spark/project/disable - Projeyi devre dışı bırak
+- DELETE /api/spark/project/{name} - Projeyi Spark'tan sil
+
+#### Chat Endpoint'leri (Yeni)
+
+- GET /api/projects/names - Chat için enabled proje listesi
+- POST /api/start_session - Chat session başlat
+- POST /api/chat - Mesaj gönder/al (Header: X-Session-ID)
+
+#### Ek Yardımcı Endpoint'ler
+
+- POST /api/validate/regex - Regex pattern validasyonu
+- POST /api/apis/test - API endpoint test etme
+- GET /api/projects/{id}/versions/diff - Version karşılaştırma
+- POST /api/projects/{id}/intents/bulk-delete - Toplu intent silme
+- GET /api/activity-log - Aktivite logları
+- POST /api/projects/import - Proje import
+- GET /api/projects/{id}/export - Proje export
+- POST /api/test/run-all - Tüm testleri çalıştır
+- GET /api/test/status - Test durumu sorgula
+
+### Service_config.jsonc düzenlemeleri:
+
+```jsonc
+{
+  "config": {
+    // Mevcut alanlar...
+    "internal_prompt": "⚠️ **NEVER output \"#DETECTED_INTENT:\"...", // Yeni
+    "project_id_counter": 1, // Yeni
+    "last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
+    "last_update_user": "admin" // Yeni
+  },
+  
+  "projects": [{
+    // Mevcut alanlar...
+    "icon": "folder", // Yeni
+    "description": "", // Yeni
+    "default_language": "tr", // Yeni
+    "supported_languages": ["tr"], // Yeni
+    "timezone": "Europe/Istanbul", // Yeni
+    "region": "tr-TR", // Yeni
+    "version_id_counter": 1, // Yeni
+    "last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
+    "last_update_user": "admin", // Yeni
+    "deleted": false, // Yeni
+    "created_date": "2025-06-08T12:00:00.000Z", // Yeni
+    "created_by": "admin", // Yeni
+    
+    "versions": [{
+      // Mevcut alanlar...
+      "last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
+      "last_update_user": "admin", // Yeni
+      "deleted": false, // Yeni
+      "created_date": "2025-06-08T12:00:00.000Z", // Yeni
+      "created_by": "admin", // Yeni
+      "publish_date": null, // Yeni
+      "published_by": null // Yeni
+    }]
+  }],
+  
+  "apis": [{
+    // Mevcut alanlar...
+    "response_mappings": [ // Yeni
+      {
+        "variable_name": "booking_id",
+        "type": "str",
+        "json_path": "confirmation.id"
+      }
+    ],
+    "last_update_date": "2025-06-08T12:00:00.000Z", // Yeni
+    "last_update_user": "admin", // Yeni
+    "deleted": false, // Yeni
+    "created_date": "2025-06-08T12:00:00.000Z", // Yeni
+    "created_by": "admin" // Yeni
+  }],
+  
+  // Yeni: Activity log
+  "activity_log": [{
+    "id": 1,
+    "timestamp": "2025-06-08T12:00:00.000Z",
+    "user": "admin",
+    "action": "CREATE_PROJECT",
+    "entity_type": "project",
+    "entity_id": 1,
+    "entity_name": "airline_agent",
+    "details": "Created new project"
+  }]
+}
+
+Tab Ekranları
+1. User Info Tab'ı
+Bu tab penceresinde login olan kullanıcı mevcut şifresini değiştirebilir. Ekrandaki alanlar:
+
+Current Password (maskeli)
+New Password (maskeli)
+New Password (tekrar, maskeli)
+Password Strength Indicator: Şifre girilirken güvenlik seviyesini gösterir (Weak/Medium/Strong)
+Save butonu
+
+Şifre değiştirebilmek için kullanıcı, maskeli alanlardan mevcut şifresini, yeni şifresini ve ikinci bir alanda teyit amaçlı olarak tekrar yeni şifresini girer ve kaydet butonuna basar. Şifre en az 8 karakter, büyük/küçük harf ve rakam içermelidir.
+2. Environment Tab'ı
+Bu tab'da aşağıdaki alanlar bulunur:
+
+Work Mode: Seçenekleri hfcloud, cloud ve on-premise olan bir combo. Zorunlu.
+Cloud Token (maskeli): Work Mode on-premise seçildiğinde disable olur.
+Spark Endpoint: URL formatında. Zorunlu. Yanında "Test Connection" butonu.
+Internal System Prompt (Yeni): Expansion panel içinde multi-line textarea. Spark'ın tüm projeler için kullanacağı temel kuralları içerir. Placeholder'lar:
+
+<intent names>: Runtime'da intent listesiyle değiştirilir
+<intent captions>: Intent caption'larıyla değiştirilir
+<project language>: Proje diline göre değiştirilir
+
+
+Save butonu
+Reload from Spark butonu: Spark'tan güncel config'i çeker
+
+3. APIs Tab'ı
+Tab açıldığında, üstte bir toolbar bulunur:
+Toolbar:
+
+New API butonu
+Import butonu: JSON dosyasından API tanımları yükler
+Export butonu: Seçili API'leri JSON olarak export eder
+Search alanı: API adı veya URL'de arama
+Display Deleted checkbox
+
+API Listesi Tablosu:
+NameURLMethodTimeoutAuthDeletedActionsbook_flight_apihttps://api.example.com/bookPOST10s✓✗🖊️ 🧪 📋 🗑️
+Action İkonları:
+
+🖊️ Edit: Edit API dialog'unu açar
+🧪 Test: API'yi test eder
+📋 Duplicate: API'nin kopyasını oluşturur
+🗑️ Delete: API'yi siler (kullanımda değilse)
+
+4. Projects Tab'ı
+Tab ekranına girildiğinde üstte toolbar bulunur:
+Toolbar:
+
+New Project butonu
+Import Project butonu
+Search alanı
+Display Deleted checkbox
+View: List/Card view toggle
+
+Proje Listesi: Kart görünümünde her proje için:
+┌─────────────────────────────────┐
+│ 🛩️ airline_agent               │
+│ Havayolu Müşteri Temsilcisi    │
+│ Language: Turkish (tr)          │
+│ Versions: 3 (1 published)       │
+│ Status: ✓ Enabled               │
+│ Last update: 2 hours ago        │
+│ [Edit] [Versions] [Export] [⚙️] │
+└─────────────────────────────────┘
+5. Chat Tab'ı (Yeni)
+Flare chat sistemini test etmek için kullanılır.
+İşleyiş:
+
+Project Selection: Enabled ve published version'u olan projeler listelenir
+Start Chat: Session başlatır, session_id alır
+Chat Interface:
+
+Mesaj history'si
+Input alanı
+Send butonu
+Session bilgileri (ID, project)
+
+
+End Session: Chat'i sonlandırır
+
+Özellikler:
+
+Real-time mesajlaşma
+Session takibi
+Auto-scroll
+Error handling
+Loading states
+
+6. Spark Integration Tab'ı (Yeni)
+Bu tab'da Spark servisi ile doğrudan etkileşim sağlanır.
+Üst Bölüm:
+
+Project Selection: Dropdown ile proje seçimi
+Proje seçildiğinde butonlar aktif olur
+
+Butonlar ve İşlevleri:
+Project Startup
+
+Seçili projeyi Spark'a yükler
+Backend üzerinden /spark/startup endpoint'ine istek atar
+Response'u detaylı olarak gösterir
+
+Get Project Status
+
+Spark'taki tüm projelerin durumunu listeler
+Tablo formatında: project_name, version, status, enabled, last_accessed
+Status badge'leri: ready (yeşil), loading (turuncu), error (kırmızı), unloaded (gri)
+
+Enable Project
+
+Seçili projeyi Spark'ta aktif hale getirir
+
+Disable Project
+
+Seçili projeyi Spark'ta devre dışı bırakır
+
+Delete Project
+
+Seçili projeyi Spark'tan tamamen siler
+Onay dialog'u gösterir
+
+Response Panel:
+
+Her işlemden sonra açılan expansion panel
+Request ve response JSON'larını gösterir
+Timestamp bilgisi
+Success/error durumu
+Son 10 işlem history'si
+
+7. Test Tab'ı
+Bu tab'da sistemin end-to-end testi yapılabilir:
+Test Kategorileri:
+
+UI Tests: Component render, navigation, form validation
+Backend Tests: API endpoint'leri, data integrity
+Integration Tests: UI-Backend entegrasyonu
+Spark Tests: LLM bağlantısı ve response kalitesi
+
+Ekran Düzeni:
+┌─────────────────────────────────────────────┐
+│ [Run All Tests] [Run Selected] [Stop]       │
+├─────────────────────────────────────────────┤
+│ □ All Tests                                 │
+│   □ UI Tests (15 tests)                     │
+│     □ Login Flow                            │
+│     □ Project CRUD                          │
+│     □ Version Management                    │
+│   □ Backend Tests (22 tests)                │
+│     □ Authentication                        │
+│     □ API Endpoints                         │
+│     □ Race Conditions                       │
+│   □ Integration Tests (18 tests)            │
+│   □ Spark Tests (8 tests)                   │
+├─────────────────────────────────────────────┤
+│ Test Results:                               │
+│ ✓ Login with valid credentials - 120ms      │
+│ ✓ Create new project - 340ms                │
+│ ✗ Delete API in use - Expected behavior     │
+│ ⏳ Testing Spark connection...               │
+│                                             │
+│ Progress: ████████░░ 80% (48/60)            │
+│ Passed: 45 | Failed: 3 | Running: 5         │
+└─────────────────────────────────────────────┤
+Test Detayları: Her test için:
+
+Test adı ve açıklaması
+Çalışma süresi
+Hata durumunda detaylı log
+"Re-run" butonu
+
+8. Activity Log (Sağ üst notification icon'a tıklandığında açılır)
+┌─────────────────────────────────────┐
+│ 🔔 Recent Activities                │
+├─────────────────────────────────────┤
+│ 2 min ago                           │
+│ 👤 admin published version 2        │
+│ of airline_agent                    │
+├─────────────────────────────────────┤
+│ 15 min ago                          │
+│ 👤 user1 updated flight_info_api    │
+├────���────────────────────────────────┤
+│ 1 hour ago                          │
+│ 👤 admin created new project        │
+│ hotel_booking                       │
+├─────────────────────────────────────┤
+│ [View All Activities]               │
+└─────────────────────────────────────┘
+Dialog Ekranları
+Edit API Dialog (Güncelleme)
+General Tab'a eklenenler:
+Response Mappings Bölümü:
+
+Variable Name: snake_case zorunlu
+Type: str, int, float, bool, date seçenekleri
+JSON Path: Dot notation ile path (örn: data.result.value)
+Add/Remove mapping butonları
+Validation: Variable name uniqueness
+
+Template Variables (Geliştirilmiş):
+
+Tüm intent parametrelerinden otomatik liste
+Response mapping değişkenleri
+Auth token değişkenleri
+Config değişkenleri (work_mode, vb.)
+Tıklanabilir chip'ler ile kolay ekleme
+
+JSON Validation (Geliştirilmiş):
+
+Numeric değişkenler için akıllı validation
+Template variable type checking
+Syntax highlighting
+
+Test Tab (Geliştirilmiş):
+
+Editable test request JSON
+Placeholder değerlerle doldurma
+Reset to template butonu
+Response preview
+
+Edit Project Dialog (Güncelleme)
+Yeni alanlar eklendi:
+
+Icon: Material icon seçimi (folder, work, shopping_cart, vb.)
+Description: Proje açıklaması
+Default Language: Varsayılan dil (tr, en, de, fr, es)
+Supported Languages: Desteklenen diller (çoklu seçim)
+Timezone: Saat dilimi (Europe/Istanbul, vb.)
+Region: Bölge kodu (tr-TR, vb.)
+
+Edit Version Dialog
+[Mevcut içerik korunacak, değişiklik yok]
+Edit Intent Dialog
+[Mevcut içerik korunacak, değişiklik yok]
+Edit Parameter Dialog
+Date type desteği eklendi:
+
+Type combo'suna "date" seçeneği
+Date formatı: YYYY-MM-DD (ISO format)
+Türkçe tarih ifadeleri için özel extraction prompt'lar
+
+Version Comparison Dialog
+[Mevcut içerik korunacak, değişiklik yok]
+Flare Admin Test Planı
+[Mevcut test planına ek olarak:]
+Spark Integration Test Senaryoları:
+
+Spark Startup Testi:
+
+Proje seç
+Startup butonuna bas
+Response'u kontrol et
+Get Status ile doğrula
+
+
+Spark Project Lifecycle:
+
+Enable → Disable → Delete akışı
+Her adımda status kontrolü
+Error handling testleri
+
+
+
+Chat Test Senaryoları:
+
+Full Chat Flow:
+
+Session başlat
+Intent detection testi
+Parameter extraction testi
+API call testi
+Session sonlandır
+
+
+Multi-turn Conversation:
+
+Eksik parametre tamamlama
+Context retention
+Session state takibi
+
+
+
+Response Mapping Testleri:
+
+Mapping Validation:
+
+Valid/invalid variable names
+Type conversion testleri
+Nested JSON path resolution
+
+
+Runtime Mapping:
+
+API response'tan değer extraction
+Session variable update
+Subsequent intent'lerde kullanım
+
+
+
+Internal Prompt Testleri:
+
+Placeholder Replacement:
+
+<intent names> doğru değişiyor mu?
+<intent captions> doğru değişiyor mu?
+<project language> project default_language'den alınıyor mu?
+
+
+Prompt Combination:
+
+Internal prompt + general prompt birleşimi
+Prompt öncelik sırası
+
+
+
+Güvenlik ve Performans
+Token Yönetimi:
+
+SPARK_TOKEN environment variable'dan alınır
+Tüm Spark isteklerinde Authorization header
+Token rotation desteği
+
+Race Condition Handling:
+
+last_update_date kontrolü tüm CRUD işlemlerinde
+Concurrent edit detection
+Optimistic locking pattern
+
+Session Management:
+
+30 dakika inactivity timeout
+Session cleanup thread
+Memory-efficient storage
+
+Teknoloji Stack
+
+Frontend: Angular 17+ (standalone components)
+UI Framework: Angular Material
+State Management: RxJS
+Backend: Python FastAPI
+Authentication: JWT
+Database: service_config.jsonc (document database pattern)
+LLM Integration: Spark servisi
+
+Bu güncellemelerle Flare Administration UI, tam fonksiyonel bir orchestration platform yönetim arayüzü haline gelmiştir.