docs: lock deepseek/deepseek-chat as assistant model, add LLM test report and harness

docs/llm-test-report.md

@@ -0,0 +1,76 @@
+# Отчёт: тестирование LLM-моделей для ассистента «Зам»
+
+**Проект:** АС «Платформа ОПОРА РОССИИ»
+**Дата:** 26.09.2026
+**Стенд:** `tools/test_models.py`
+**Провайдер:** OpenRouter
+
+---
+
+## 1. Цель
+
+Выбрать LLM для AI-ассистента «Зам» (п. 4.2.14 ТЗ, Вариант 1) по критериям: русский язык, function calling, структурированный вывод, стоимость, латентность.
+
+## 2. Методика
+
+Три тестовых сценария, приближенных к задачам ассистента:
+
+| Тест | Что проверяет |
+|---|---|
+| `ru_generation` | Генерация «Еженедельного фокуса целей» на русском с терминологией |
+| `function_calling` | Вызов инструмента `create_task` с корректными аргументами |
+| `json_output` | Структурированный JSON (region, point0, current, growth) |
+
+## 3. Результаты
+
+**Модель: `deepseek/deepseek-chat`**
+
+| Тест | Статус | Латентность | Токены (prompt+completion) | Стоимость |
+|---|---|---|---|---|
+| `ru_generation` | ✅ OK | 9.65 с | 150 + 160 | $0.00019 |
+| `function_calling` | ✅ OK | 3.55 с | 891 + 62 | $0.00034 |
+| `json_output` | ✅ OK | 3.34 с | 135 + 41 | $0.00008 |
+
+**Средняя латентность:** 5.51 с · **Стоимость прогона:** $0.00061
+
+### Пример ответа (`ru_generation`)
+
+> **Еженедельный фокус целей: Донецкая Народная Республика**
+> Прирост от точки 0: **+136**.
+> Округ ЮФО: **+365**, динамика: **12/12 регионов**.
+>
+> **Что делать:**
+> 1. Усилить поддержку предпринимателей…
+
+### Проверка function calling
+
+Модель корректно вызвала `create_task` со всеми обязательными полями:
+`title`, `due_date` (= 2026-10-01), `priority` (= высокий), `assignee` (= регион ДНР).
+
+### Проверка JSON
+
+Модель вернула валидный JSON с полями `region`, `point0`, `current`, `growth` (= 136).
+
+## 4. Оценка стоимости в продакшене
+
+| Объём действий/мес | Оценка стоимости |
+|---|---|
+| 10 000 | ~$3 |
+| 100 000 | ~$30 |
+
+Стоимость пренебрежимо мала относительно бюджета проекта.
+
+## 5. Вывод
+
+`deepseek/deepseek-chat` полностью подходит под задачи ассистента «Зам»: качественный русский язык, надёжный function calling, стабильный JSON, низкая стоимость. Латентность 3–10 с приемлема; при необходимости снижается стримингом ответа.
+
+**Решение:** модель ассистента — `deepseek/deepseek-chat` (OpenRouter). PiAPI — резерв (медиа), не используется на текущем этапе.
+
+## 6. Воспроизведение
+
+```powershell
+$env:OPENROUTER_API_KEY = "<ключ>"
+py -3 tools/test_models.py --models "deepseek/deepseek-chat"
+```
+
+> Ключ API в репозиторий не сохраняется.

docs/stack.md

@@ -31,7 +31,7 @@
 | Мониторинг | **Prometheus + Grafana + Loki** | Метрики, логи, алерты |
 | Бэкапы | **Отложены** (см. раздел 5) | Принятый риск на текущем этапе |
 | CI/CD | **GitLab CI** | Сборка образов, деплой на сервер |
-| AI-ассистент «Зам» | **Внешний LLM API: OpenRouter / PiAPI** | Без GPU; выбор модели — в тестировании (см. раздел 8) |
+| AI-ассистент «Зам» | **OpenRouter → `deepseek/deepseek-chat`** | Без GPU; модель выбрана по тестам (раздел 8). PiAPI — резерв (медиа) |
 
 ---
 
@@ -144,35 +144,35 @@ OpenRouter и PiAPI — зарубежные сервисы, данные ухо
 
 ---
 
-## 8. AI-ассистент: тестирование моделей
+## 8. AI-ассистент: выбранная модель
 
-Выбор LLM — в тестировании. Критерии оценки:
+**Модель: `deepseek/deepseek-chat` (через OpenRouter).**
 
-| Критерий | Что проверяем |
-|---|---|
-| Русский язык | Качество текста, терминология («точка 0», «прирост», «красная зона») |
-| Function calling | Надёжность вызова инструментов (заполнить карточку, создать задачу, загрузить артефакт) |
-| Стоимость | Цена за 1M токенов, оценка месячного бюджета |
-| Скорость | Латентность ответа |
-| Контекст | Размер окна (сводки по 89 регионам) |
-| Стабильность | Повторяемость структурированного вывода (JSON) |
+Выбор сделан по результатам тестирования (стенд `tools/test_models.py`, отчёт — `docs/llm-test-report.md`).
 
-Кандидаты (через OpenRouter): GPT-4o / GPT-4o-mini, Claude (Sonnet/Haiku), Gemini Flash, Qwen, DeepSeek, Mistral.
-PiAPI — уточнить назначение (генерация изображений/медиа для артефактов или LLM).
+| Тест | Статус | Латентность | Стоимость |
+|---|---|---|---|
+| Русский текст (еженедельный фокус целей) | ✅ OK | 9.65 с | $0.00019 |
+| Function calling (`create_task`) | ✅ OK | 3.55 с | $0.00034 |
+| Структурированный JSON | ✅ OK | 3.34 с | $0.00008 |
+
+**Оценка стоимости:** ~$0.0002–0.0003 за действие ассистента → ~$3/мес при 10 000 действий, ~$30/мес при 100 000.
+
+**Критерии, по которым оценивалась модель:** русский язык и терминология, надёжность function calling, стоимость, латентность, размер контекста, стабильность JSON.
+
+**PiAPI** — резервный вариант (генерация медиа), на текущем этапе не используется.
 
 ---
 
 ## 9. Открытые вопросы
 
-1. **Модель LLM** — по результатам тестирования (раздел 8).
-2. **Назначение PiAPI** — LLM или генерация медиа.
-3. **Бэкапы** — когда включать (отложено).
-4. **Реестр отечественного ПО** — нужен ли в перспективе.
+1. **Бэкапы** — когда включать (отложено).
+2. **Реестр отечественного ПО** — нужен ли в перспективе.
+3. **PiAPI** — назначение и момент подключения (резерв).
 
 ---
 
 ## 10. Следующие шаги
 
-1. Провести тестирование LLM-моделей (раздел 8).
-2. Утвердить документ.
-3. Перейти к техническому проекту: структура БД, контракты API, макеты экранов.
+1. Утвердить документ.
+2. Перейти к техническому проекту: структура БД, контракты API, макеты экранов.