# Интеграция AI

---

## Паттерн: FallbackChain

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

### Реализация

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

```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? (да, если конфиденциальность критична)