docs/flare-tasarim.md

# 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ı

```json

{

  "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
```json

{

  "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
```json

{

  "name": "provider_name",

  "api_key": "enc:encrypted_key",

  "endpoint": "https://endpoint",

  "settings": {

    // Provider-specific ayarlar

  }

}

```

### Project Yapısı
```json

{

  "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ı
```json

{

  "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ı
```json

{

  "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ı
```json

{

  "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ı
```json

{

  "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
```python

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:

1. **Otomatik parametre ekleme**: `is_approved` parametresi dinamik olarak eklenir
2. **Onay sorusu oluşturma**: API description'daki placeholder'lar değiştirilir
3. **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
```python

# 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

```python

# 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
1. **Variable substitution**: `{{variables.xxx}}` → gerçek değerler
2. **Auth token yönetimi**: Otomatik token alma ve yenileme
3. **Retry logic**: Configurable retry stratejisi
4. **Response mapping**: JSON path ile veri çıkarma
5. **Response humanization**: LLM ile insanileştirme

### Auth Mekanizması
```python

# 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
```json

{

  "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

```json

{

  "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
```bash

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
```python

@app.get("/")

def health():

    return {"status": "ok"}



# Hugging Face için daemon thread

threading.Thread(target=run_health_server, daemon=True).start()

```