docs/CONFIGURATION.md

Конфігурація додатку

📋 Огляд

Вся конфігурація додатку зберігається в config/environments/default.yaml як єдине джерело істини.

Pydantic моделі в config/settings.py використовуються тільки для валідації типів та значень, без дефолтних значень.

🎯 Принципи

✅ Правильний підхід

YAML файл → Єдине джерело істини (всі значення)
    ↓
Pydantic → Валідація типів (БЕЗ дефолтів)
    ↓
Python код → Використання через get_settings()

❌ Неправильний підхід (дубляж)

# ❌ НЕ робити так!
class AppConfig(BaseModel):
    name: str = "Legal Position"  # ← Дубляж з YAML

📁 Структура конфігурації

config/environments/default.yaml

# Єдине джерело істини для всіх налаштувань
app:
  name: "Legal Position AI Analyzer"
  version: "1.0.0"
  debug: false
  environment: "production"

models:
  default_provider: "gemini"  # ← Провайдер за замовчуванням
  providers:
    - openai
    - anthropic
    - gemini
    - deepseek

config/settings.py

# Тільки типи та валідація, БЕЗ дефолтів
class AppConfig(BaseModel):
    name: str          # ← Тільки тип
    version: str       # ← Тільки тип
    debug: bool
    environment: str

config/models.py

# Динамічна генерація enums з YAML
GenerationModelName = Enum(
    'GenerationModelName',
    _registry.get_generation_models(),  # ← З YAML
    type=str
)

🔧 Використання

Отримання налаштувань

from config import get_settings

settings = get_settings()

# Доступ до значень
app_name = settings.app.name
default_provider = settings.models.default_provider
timeout = settings.session.timeout_minutes

Отримання моделей

from config import GenerationModelName, ModelProvider

# Enum згенерований з YAML
model = GenerationModelName.GEMINI_3_FLASH

# Провайдер
provider = ModelProvider.GEMINI

Зміна дефолтного провайдера

Крок 1: Змінити в YAML

# config/environments/default.yaml
models:
  default_provider: "gemini"  # ← Змінити тут

Крок 2: Оновити UI (якщо потрібно)

# interface.py
generation_provider_dropdown = gr.Dropdown(
    value=ModelProvider.GEMINI.value  # ← Синхронізувати
)

📊 Поточні налаштування

Провайдери

Параметр	Значення	Файл
Default Provider (Generation)	gemini	YAML
Default Provider (Analysis)	gemini	YAML
Default Model (Generation)	gemini-3-flash-preview	YAML
Default Model (Analysis)	gemini-3-flash-preview	YAML

Сесії

Параметр	Значення	Опис
timeout_minutes	30	Таймаут сесії
cleanup_interval_minutes	5	Інтервал очистки
max_sessions	1000	Максимум сесій
storage_type	memory	Тип зберігання

LlamaIndex

Параметр	Значення	Опис
context_window	20000	Розмір контексту
chunk_size	2048	Розмір чанка
similarity_top_k	20	К-сть результатів
embed_model	text-embedding-3-small	Модель ембедінгу

Gradio

Параметр	Значення	Опис
server_name	0.0.0.0	Адреса сервера
server_port	7860	Порт
share	true	Публічний доступ

🔄 Ієрархія конфігурації

1. Environment Variables (.env)
   ↓
2. YAML Configuration (default.yaml)
   ↓
3. Pydantic Validation (settings.py)
   ↓
4. Runtime Settings (get_settings())

Environment Variables

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AI...
DEEPSEEK_API_KEY=sk-...

YAML приоритет

Якщо потрібно перевизначити для різних середовищ:

config/environments/
├── default.yaml      # ← Базові налаштування
├── development.yaml  # ← Для розробки (опціонально)
└── production.yaml   # ← Для production (опціонально)

🎨 Додавання нової моделі

Крок 1: Додати в YAML

# config/environments/default.yaml
models:
  generation:
    gemini:
      - name: "gemini-3-flash-preview"
        display_name: "Gemini 3 Flash"
        default: true
      - name: "gemini-4-ultra"  # ← Нова модель
        display_name: "Gemini 4 Ultra"

Крок 2: Перезапустити додаток

Enum автоматично згенерується з нової конфігурації.

# Автоматично доступно
from config import GenerationModelName
GenerationModelName.GEMINI_4_ULTRA  # ✅ Працює!

🔒 Валідація

Автоматична валідація при завантаженні

# config/loader.py
settings = loader.load_config(validate_api_keys=True)

# Перевіряє:
# ✅ Типи даних (int, str, bool, etc.)
# ✅ Обов'язкові поля
# ✅ Діапазони значень
# ✅ Формати (email, URL, etc.)
# ✅ API ключі (якщо validate_api_keys=True)

Кастомна валідація

# config/settings.py
@validator('storage_type')
def validate_storage_type(cls, v):
    allowed = ["memory", "redis"]
    if v not in allowed:
        raise ValueError(f"storage_type must be one of {allowed}")
    return v

📝 Найкращі практики

✅ DO

1. Всі дефолти в YAML

   session:
     timeout_minutes: 30  # ✅
   

2. Pydantic тільки для типів

   class SessionConfig(BaseModel):
       timeout_minutes: int  # ✅ Тільки тип
   

3. Використання через get_settings()

   settings = get_settings()
   timeout = settings.session.timeout_minutes  # ✅
   

❌ DON'T

1. Не дублювати значення

   # ❌ Неправильно
   timeout_minutes: int = 30  # Дубляж з YAML
   

2. Не хардкодити в коді

   # ❌ Неправильно
   TIMEOUT = 30  # Має бути в YAML
   

3. Не ігнорувати валідацію

   # ❌ Неправильно
   arbitrary_types_allowed = True  # Без необхідності
   

🐛 Troubleshooting

Проблема: Зміни в YAML не застосовуються

Рішення: Перезапустити додаток

# Зупинити
Ctrl+C

# Запустити знову
python main.py

Проблема: Помилка валідації

pydantic.error_wrappers.ValidationError:
  timeout_minutes
    field required (type=value_error.missing)

Рішення: Перевірити наявність поля в YAML

# config/environments/default.yaml
session:
  timeout_minutes: 30  # ← Додати, якщо відсутнє

Проблема: Модель не знайдена

AttributeError: 'GenerationModelName' has no attribute 'GEMINI_3_FLASH'

Рішення: Перевірити назву в YAML та перезапустити

models:
  generation:
    gemini:
      - name: "gemini-3-flash-preview"  # ← Точна назва

🔍 Перевірка конфігурації

Команда для перевірки

from config import get_settings

settings = get_settings()

print(f"App: {settings.app.name}")
print(f"Default provider: {settings.models.default_provider}")
print(f"Session timeout: {settings.session.timeout_minutes}m")

Очікуваний вихід

App: Legal Position AI Analyzer
Default provider: gemini
Session timeout: 30m

📚 Додаткова інформація

• Повна конфігурація: config/environments/default.yaml
• Pydantic моделі: config/settings.py
• Генерація enums: config/models.py
• Завантажувач: config/loader.py

---

Останнє оновлення: 2025-12-28

Статус: ✅ Без дубляжів, Gemini за замовчуванням