Initial commit: VoIdeaAI - voice-first AI idea assistant

2026-05-13 12:51:42 +03:00
commit 688d043dad
421 changed files with 47915 additions and 0 deletions
@@ -0,0 +1,91 @@
+# Интеграция 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? (да, если конфиденциальность критична)