Flare Platform - Güncel Tasarım Dokümanı

🏗 Genel Mimari

Flare, modüler LLM provider desteği ile çalışan çok adımlı ve akıllı bir orchestration katmanıdır. Provider-agnostic tasarımı sayesinde farklı LLM, TTS ve STT motorları ile çalışabilir.

Temel Özellikler

✅ Provider-based mimari (LLM, TTS, STT)
✅ Intent detection ve parameter extraction
✅ Akıllı parametre toplama (smart grouping)
✅ Onay mekanizması (requiresApproval)
✅ Multi-language destek (LocalizedExample, LocalizedCaption)
✅ Session-based state machine
✅ API orchestration ve response mapping
✅ Activity logging ve audit trail

📋 Konfigürasyon Yapısı

service_config.jsonc - Ana Yapı

{
  "config": {
    // Provider tanımları
    "llm_provider": {
      "name": "spark|gpt4o|gpt4o-mini",
      "api_key": "enc:...",  // Şifrelenmiş
      "endpoint": "https://...",
      "settings": {
        "internal_prompt": "Global LLM yönergesi",
        "parameter_collection_config": {
          "max_params_per_question": 2,
          "smart_grouping": true,
          "retry_unanswered": true,
          "collection_prompt": "..."
        }
      }
    },
    "tts_provider": {
      "name": "no_tts|elevenlabs|blaze",
      "api_key": "enc:...",
      "endpoint": null,
      "settings": {}
    },
    "stt_provider": {
      "name": "no_stt|google|azure|flicker",
      "api_key": "/path/to/credentials.json",
      "endpoint": null,
      "settings": {
        "language": "tr-TR",
        "model": "latest_long"
      }
    },
    "providers": [
      // Kullanılabilir provider tanımları
    ],
    "users": [...]
  },
  "projects": [...],
  "apis": [...],
  "activity_log": [...],
  "project_id_counter": 1,
  "last_update_date": null,
  "last_update_user": null
}

Provider Sistemi

Provider Config

{
  "type": "llm|tts|stt",
  "name": "spark",
  "display_name": "Spark LLM",
  "requires_endpoint": true,
  "requires_api_key": true,
  "requires_repo_info": false,
  "description": "YTU Cosmos Spark LLM"
}

Provider Settings

{
  "name": "provider_name",
  "api_key": "enc:encrypted_key",
  "endpoint": "https://endpoint",
  "settings": {
    // Provider-specific ayarlar
  }
}

Project Yapısı

{
  "id": 1,
  "name": "project_name",
  "caption": "Proje Başlığı",
  "icon": "folder",
  "description": "Açıklama",
  "enabled": true,
  "default_locale": "tr",
  "supported_locales": ["tr", "en"],
  "timezone": "Europe/Istanbul",
  "region": "tr-TR",
  "versions": [...],
  "version_id_counter": 1,
  "deleted": false,
  "created_date": "2024-01-01T00:00:00Z",
  "created_by": "username",
  "last_update_date": null,
  "last_update_user": null
}

Version Yapısı

{
  "id": 1,
  "no": 1,
  "caption": "v1",
  "description": "Version açıklaması",
  "published": true,
  "deleted": false,
  "general_prompt": "Asistan için genel yönerge",
  "welcome_prompt": "Hoşgeldin mesajı yönergesi",
  "llm": {
    "repo_id": "model-id",
    "generation_config": {},
    "use_fine_tune": false,
    "fine_tune_zip": ""
  },
  "intents": [...],
  "created_date": "2024-01-01T00:00:00Z",
  "created_by": "username",
  "publish_date": null,
  "published_by": null
}

Intent Yapısı

{
  "name": "intent_name",
  "caption": "Intent Başlığı",
  "requiresApproval": false,
  "dependencies": [],
  "examples": [
    {
      "locale_code": "tr",
      "example": "Örnek cümle"
    }
  ],
  "detection_prompt": "Intent algılama yönergesi",
  "parameters": [...],
  "action": "api_name",
  "fallback_timeout_prompt": "Zaman aşımı mesajı",
  "fallback_error_prompt": "Hata mesajı"
}

Parameter Yapısı

{
  "name": "param_name",
  "caption": [
    {
      "locale_code": "tr",
      "caption": "Parametre Başlığı"
    }
  ],
  "type": "str|int|float|bool|date",
  "required": true,
  "variable_name": "variable_name",
  "extraction_prompt": "Parametre çıkarma yönergesi",
  "validation_regex": "^pattern$",
  "invalid_prompt": "Geçersiz değer mesajı",
  "type_error_prompt": "Tip hatası mesajı"
}

API Yapısı

{
  "name": "api_name",
  "description": "{{variables.x}} için işlem açıklaması",
  "url": "https://api-endpoint",
  "method": "GET|POST|PUT|DELETE",
  "headers": "{}",  // JSON string
  "body_template": "{}",  // JSON string
  "timeout_seconds": 10,
  "retry": {
    "max_attempts": 3,
    "backoff_seconds": 2,
    "strategy": "static|exponential"
  },
  "auth": {
    "enabled": true,
    "token_endpoint": "https://auth-endpoint",
    "response_token_path": "access_token",
    "token_request_body": "{}",
    "token_refresh_endpoint": null,
    "token_refresh_body": "{}"
  },
  "response_mappings": [
    {
      "variable_name": "result",
      "caption": "Sonuç",
      "type": "str",
      "json_path": "$.data.result"
    }
  ],
  "response_prompt": "Response insanileştirme yönergesi",
  "deleted": false,
  "created_date": "2024-01-01T00:00:00Z",
  "created_by": "username"
}

🔄 Session ve State Yönetimi

Session Özellikleri

class Session:
    session_id: str
    project_name: str
    version_number: int
    version_config: VersionConfig
    
    # State machine
    state: str  # idle | await_param | call_api | humanize
    last_intent: str | None
    awaiting_parameters: List[str]
    missing_ask_count: int
    
    # Data storage
    variables: Dict[str, str]
    auth_tokens: Dict[str, Dict]
    chat_history: List[Dict[str, str]]
    
    # Smart parameter tracking
    asked_parameters: Dict[str, int]
    unanswered_parameters: List[str]
    parameter_ask_rounds: int
    
    # Real-time support
    is_realtime_session: bool
    active_websocket: Any

State Machine Flow

start_session → welcome_prompt
     ↓
    idle ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ←
     ↓                                             ↑
detect_intent → collect_params → approval? → call_api → humanize
                      ↑              ↓
                      ← await_param ←

🔐 Onay Mekanizması

Intent'te requiresApproval: true olduğunda:

Otomatik parametre ekleme: is_approved parametresi dinamik olarak eklenir
Onay sorusu oluşturma: API description'daki placeholder'lar değiştirilir
Onay kontrolü:
- Onay verilirse → API çağrısı
- Onay verilmezse → İşlem iptali

🌍 Multi-Language Destek

Locale Yönetimi

Project seviyesinde default_locale ve supported_locales
LocalizedExample ve LocalizedCaption yapıları
Locale JSON dosyaları (tr.json, en.json, vb.)

LocaleManager

# Locale bilgilerini yönetir
LocaleManager.get_locale("tr")
LocaleManager.format_date(date, "tr")
LocaleManager.parse_date_expression("yarın", "tr")
LocaleManager.format_number(1234.56, "tr")

🎤 TTS/STT Entegrasyonu

TTS Providers

ElevenLabs: Yüksek kaliteli, çok dilli
Blaze: Alternatif TTS
No TTS: Devre dışı

STT Providers

Google: Cloud Speech-to-Text
Azure: Azure Speech Services
Flicker: Alternatif STT
No STT: Devre dışı

Real-time Features

WebSocket-based audio streaming
Voice Activity Detection (VAD)
Noise reduction
Interim results

🚀 LLM Provider Desteği

Spark

YTU Cosmos modelleri
HuggingFace Cloud veya on-premise
Custom fine-tuning desteği

GPT-4o / GPT-4o-mini

OpenAI API entegrasyonu
Temperature ve max_tokens kontrolü
Maliyet optimizasyonu

Provider Seçimi

# chat_handler.py
if llm_provider.name == "spark":
    llm = SparkLLM(endpoint, token)
elif llm_provider.name.startswith("gpt4o"):
    llm = GPT4oLLM(api_key, model)

📡 API Yönetimi

API Çağrı Süreci

Variable substitution: {{variables.xxx}} → gerçek değerler
Auth token yönetimi: Otomatik token alma ve yenileme
Retry logic: Configurable retry stratejisi
Response mapping: JSON path ile veri çıkarma
Response humanization: LLM ile insanileştirme

Auth Mekanizması

# Token alma ve cache'leme
if api.auth.enabled:
    token = get_or_refresh_token(api, session)
    headers["Authorization"] = f"Bearer {token}"

🔒 Güvenlik

Encryption

API key'ler enc: prefix ile şifrelenmiş saklanır
Fernet encryption (symmetric)
Environment variable: FERNET_KEY

Authentication

JWT-based session yönetimi
Bcrypt password hashing
Session timeout kontrolü

Race Condition Koruması

last_update_date ile optimistic locking
Thread-safe session store
Concurrent update kontrolü

📊 Monitoring ve Logging

Activity Log

{
  "timestamp": "2024-01-01T00:00:00Z",
  "username": "admin",
  "action": "CREATE_PROJECT",
  "entity_type": "project",
  "entity_id": 1,
  "entity_name": "project_name",
  "details": "Additional info"
}

Log Actions

Project CRUD: CREATE, UPDATE, DELETE, ENABLE, DISABLE
Version: CREATE, UPDATE, PUBLISH, DELETE
API: CREATE, UPDATE, DELETE
Environment: UPDATE_ENVIRONMENT
Import/Export: IMPORT_PROJECT, EXPORT_PROJECT

🧪 Test ve Development

Mock Backend

Scenario-based testing
Configurable responses
Error simulation

Debug Features

Detailed timestamped logging
Request/Response tracking
Performance metrics

🔄 Import/Export

Project Export Format

{
  "name": "project_name",
  "caption": "Project Caption",
  "icon": "folder",
  "description": "Description",
  "default_locale": "tr",
  "supported_locales": ["tr", "en"],
  "versions": [
    {
      "caption": "v1",
      "general_prompt": "...",
      "llm": {...},
      "intents": [...]
    }
  ]
}

🚦 Production Deployment

Docker Support

HuggingFace Spaces uyumlu
Health check endpoint
Environment-based configuration
Volume mount için permission handling

Environment Variables

FERNET_KEY=...           # Encryption key
SPARK_TOKEN=...          # Spark API token
OPENAI_API_KEY=...       # GPT-4o key
GOOGLE_APPLICATION_CREDENTIALS=... # STT credentials
HF_HOME=/app/.cache      # HuggingFace cache

Health Check

@app.get("/")
def health():
    return {"status": "ok"}

# Hugging Face için daemon thread
threading.Thread(target=run_health_server, daemon=True).start()