Initial commit: VoIdeaAI - voice-first AI idea assistant

template/docs/agent-prompts/README.md

@@ -0,0 +1,64 @@
+# Управление промптами агентов
+
+---
+
+## Принцип
+
+Промпты — это код. Они версионируются, хранятся в репозитории и проходят code review.
+Никаких hardcoded промптов в Python-коде.
+
+---
+
+## Где хранить
+
+### Вариант A: YAML (рекомендован)
+`docs/agent_prompts.yaml`
+
+```yaml
+coordinator:
+  system_prompt: "Ты — координатор. Твоя задача..."
+  provider: yandex_gpt
+  temperature: 0.7
+  max_tokens: 2000
+```
+
+**Плюсы:** Простота редактирования, структурированность, легко парсить.
+**Минусы:** Сложные промпты с примерами неудобно читать в YAML.
+
+### Вариант B: Markdown
+`docs/specs/agents/coordinator.md`
+
+```markdown
+## Prompt Template
+```
+Ты — координатор. Твоя задача...
+```
+```
+
+**Плюсы:** Читаемость, поддержка форматирования, примеры.
+**Минусы:** Сложнее парсить, нет структуры.
+
+### Рекомендация
+**YAML для настроек + MD для детальных спецификаций.**
+`PromptLoader` пробует YAML, если не нашёл — падает на MD.
+
+---
+
+## Структура YAML
+
+```yaml
+coordinator:
+  system_prompt: "текст промпта"
+  provider: "yandex_gpt"       # какой провайдер
+  temperature: 0.7              # креативность (0.0-1.0)
+  max_tokens: 2000              # макс. длина ответа
+  model: "yandexgpt/latest"     # конкретная модель (опционально)
+```
+
+---
+
+## [ASK]
+
+- Какой формат выбрать? (рекомендация: YAML для быстрых промптов, MD для сложных)
+- Нужна ли валидация промптов? (да, проверять что все placeholder'ы заполнены)
+- Кто редактирует промпты? (разработчики + AI-агенты через EvolutionAgent)

template/docs/agent-prompts/patterns.md

@@ -0,0 +1,61 @@
+# Паттерны промптов
+
+---
+
+## 1. System + User разделение
+
+```python
+system_prompt = "Ты — бизнес-аналитик. Анализируй идеи."
+user_prompt = f"Название: {idea.title}\nОписание: {idea.content}"
+
+# Формирование:
+full_prompt = f"{system_prompt}\n\n{user_prompt}"
+```
+
+**Используется:** AIProvider.format_prompt()
+
+---
+
+## 2. Structured output
+
+```python
+system_prompt = """
+Ты — финансовый консультант.
+Ответ верни ТОЛЬКО в формате JSON:
+{
+    "roi": число,
+    "risk_level": "low|medium|high",
+    "recommendations": [строка, ...]
+}
+"""
+```
+
+---
+
+## 3. Few-shot (примеры)
+
+```python
+system_prompt = """
+Ты — UI-дизайнер. Анализируй интерфейс.
+
+Пример хорошего анализа:
+Интерфейс: Экран входа
+Проблема: Кнопка "Забыли пароль" не видна
+Решение: Переместить под форму входа
+Рекомендация: Высокий приоритет
+
+Теперь проанализируй:
+"""
+```
+
+---
+
+## Параметры
+
+| Параметр | Значение | Когда менять |
+|----------|----------|-------------|
+| `temperature: 0.1-0.3` | Низкая креативность | Юридические, финансовые промпты |
+| `temperature: 0.5-0.7` | Средняя | Стандартный анализ |
+| `temperature: 0.8-1.0` | Высокая | Мозговой штурм, креатив |
+| `max_tokens: 500` | Короткий ответ | Классификация |
+| `max_tokens: 4000` | Длинный ответ | Детальный анализ |

template/docs/agent-prompts/storage.md

@@ -0,0 +1,103 @@
+# Хранение и загрузка промптов
+
+---
+
+## Загрузчик (PromptLoader)
+
+```python
+from pathlib import Path
+import yaml, re
+
+AGENT_SPECS_DIR = Path("docs/specs/agents")
+AGENT_PROMPTS_YAML = Path("docs/agent_prompts.yaml")
+
+def get_prompt_config(role: str) -> dict | None:
+    """Get prompt config for a role."""
+    # 1. Пробуем YAML
+    config = _load_from_yaml(role)
+    if config:
+        return config
+    # 2. Пробуем MD
+    return _load_from_spec(role)
+
+def _load_from_yaml(role: str) -> dict | None:
+    """Load from docs/agent_prompts.yaml."""
+    if not AGENT_PROMPTS_YAML.exists():
+        return None
+    data = yaml.safe_load(AGENT_PROMPTS_YAML.read_text(encoding="utf-8"))
+    return data.get(role) if data else None
+
+def _load_from_spec(role: str) -> dict | None:
+    """Load from docs/specs/agents/<role>.md."""
+    spec_path = AGENT_SPECS_DIR / f"{role}.md"
+    if not spec_path.exists():
+        return None
+    content = spec_path.read_text(encoding="utf-8")
+    match = re.search(r"## Prompt Template\n+```\n(.+?)\n```", content, re.DOTALL)
+    if not match:
+        return None
+    return {
+        "system_prompt": match.group(1).strip(),
+        "provider": "yandex_gpt",
+        "temperature": 0.7,
+        "max_tokens": 2000,
+    }
+```
+
+---
+
+## Пример 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
+
+legal_expert:
+  system_prompt: "Ты — юрист..."
+  provider: gigachat  # Для юридических вопросов
+  temperature: 0.3
+  max_tokens: 3000
+```
+
+---
+
+## Пример MD-файла
+
+`docs/specs/agents/business_analyst.md`
+
+```markdown
+# Бизнес-аналитик
+
+**Провайдер:** Yandex GPT
+**Температура:** 0.5
+**Макс. токенов:** 3000
+
+## Prompt Template
+```
+Ты — бизнес-аналитик.
+Проанализируй идею и оцени:
+1. Целевую аудиторию
+2. ROI
+3. Сроки реализации
+...
+```
+```
+
+---
+
+## [ASK]
+
+- Какой формат использовать по умолчанию? (рекомендация: YAML + MD fallback)
+- Нужна ли валидация placeholder'ов в промптах? (да, {...} должны быть заменены)
+- Нужна ли версионирование промптов? (да, через git — каждый промпт MD/YAML файл)

template/docs/agent-prompts/templates/prompt_md_template.md

@@ -0,0 +1,19 @@
+# {Role Name}
+
+**Провайдер:** {yandex_gpt | gigachat}
+**Температура:** {0.1-1.0}
+**Макс. токенов:** {500-4000}
+
+## Описание
+
+{Краткое описание роли AI-агента. Что делает, какие вопросы решает.}
+
+## Prompt Template
+
+```text
+Ты — {role_name}. {описание}.
+
+{инструкции}
+
+{формат ответа}
+```

template/docs/agent-prompts/templates/prompt_yaml_template.yaml

@@ -0,0 +1,14 @@
+# Шаблон промпта в YAML
+# Используйте как основу для нового AI-агента
+
+role_name:
+  system_prompt: |
+    Ты — {role_name}. {описание роли}.
+    
+    {инструкции}
+    
+    {формат ответа}
+  provider: yandex_gpt    # или gigachat
+  temperature: 0.7        # 0.1-1.0
+  max_tokens: 2000        # макс. длина
+  model: ""               # опционально: конкретная модель