voidea/template/docs/decisions/03-ai-integration.md

Интеграция AI

---

Паттерн: FallbackChain

Запрос → Provider 1 → Успех → результат
                        Ошибка → Provider 2 → Успех → результат
                                               Ошибка → Fallback результат

Реализация

class FallbackChain:
    def __init__(self, providers: list[AIProvider], max_retries: int = 2):
        self.providers = providers
        self.max_retries = max_retries

    async def analyze(self, prompt: str, **kwargs) -> AIResult:
        last_error = None
        for provider in self.providers:
            for attempt in range(self.max_retries + 1):
                try:
                    result = await provider.analyze(prompt, **kwargs)
                    if result.success:
                        return result
                    last_error = result
                except Exception as e:
                    last_error = AIResult(success=False, error=str(e))
                if attempt < self.max_retries:
                    await asyncio.sleep(2 if attempt == 0 else 5)
        return last_error or AIResult(success=False, error="All providers failed")

---

Таймауты и ретраи (следуя §12 правил)

1. Попытка (timeout: 10s)
2. Успех → return
3. Таймаут → retry 1 (через 2s)
4. Таймаут → retry 2 (через 5s)
5. 4xx → WARNING, return fallback
6. 5xx → ERROR, retry → fallback
7. Все retry исчерпаны → return fallback

---

Хранение промптов

Рекомендуемый формат: YAML (docs/agent_prompts.yaml)

coordinator:
  system_prompt: "Ты — координатор проекта..."
  provider: yandex_gpt
  temperature: 0.7
  max_tokens: 2000

business_analyst:
  system_prompt: "Ты — бизнес-аналитик..."
  provider: yandex_gpt
  temperature: 0.5
  max_tokens: 3000

Альтернатива: MD-файлы в docs/specs/agents/ (для детальных спецификаций)

---

Провайдеры

Провайдер	Когда	Аутентификация
Yandex GPT	РФ, хорошая русская речь	IAM token или API key
GigaChat (Sber)	РФ, юридические/финансовые темы	OAuth client credentials
OpenAI	Международные проекты	API key
Локальная модель	Оффлайн, конфиденциальность	Не требуется

---

[ASK]

• Какие AI провайдеры нужны? (рекомендация: минимум 2 для fallback)
• Нужен ли fallback chain? (да — обязателен для отказоустойчивости)
• Где хранить промпты? (рекомендация: YAML — простота редактирования)
• Нужен ли локальный AI? (да, если конфиденциальность критична)