2026-05-13 media-toolbox: архитектурные заметки — кеш, OpenRouter, встроенный агент

family/projects/media-toolbox-kraken.md

@@ -73,7 +73,44 @@ TrueNAS (Taiga)
 
 ---
 
-## Шаг 1 — Исследование: Kodi lib на HTPC
+## Важные замечания по архитектуре
+
+### Кеширование API-ответов ✅
+`HTTPClient` кеширует все ответы в файловую систему (30-дневный TTL), включая при dry run. Кеш: `/srv/.../docker/media-pipeline/cache/`. Повторные resolve-прогоны не тратят API-лимиты.
+
+### AI-агент: OpenRouter вместо OpenAI
+`ChatGPTAPI` переключён на `https://openrouter.ai/api/v1/chat/completions`, модель по умолчанию `openai/gpt-4o-mini:free`. Ключ: `openai_api_key` в config.json — нужен реальный `sk-or-v1-...` ключ с openrouter.ai (бесплатный tier достаточен для Tier 5 last-resort).
+
+### Встроенный агент вместо Hermes cron ⭐
+**Идея (под вопросом / для реализации):** вместо внешнего Hermes cron-джоба — встроить в `media-pipeline` интерактивный режим `resolve --interactive` (или отдельная команда `agent`).
+
+Концепция:
+- Для файлов которые не нашлись через TMDB/KP/webSearch — не просто записать "unresolved", а запустить mini-агентскую сессию
+- Агент имеет промпты + тулы (веб-поиск, TMDB по ID, Kinopoisk по ID, пользовательский ввод)
+- Может задавать уточняющие вопросы если нашёл несколько кандидатов
+- Сохраняет результат в кеш чтобы последующие прогоны не тратили API
+- Это делает media-pipeline самодостаточным — не зависит от внешнего оркестратора
+
+Преимущества vs Hermes cron:
+- Нет latency между обнаружением проблемы и её решением
+- Контекст resolve-сессии доступен агенту напрямую (graph facts, провайдеры, история)
+- Работает как download-complete хук: скачал → resolve → если не нашёл → агент разбирается тут же
+
+Реализация (примерно):
+```swift
+// media-pipeline agent --config /config/config.json [--path ...]
+// Запускает resolve, для unresolved — интерактивная LLM-сессия с тулами
+struct AgentCommand {
+    // Инструменты:
+    // - tmdb_search(query, year) → candidates[]
+    // - kp_search(query) → candidates[]
+    // - web_search(query) → snippets[]
+    // - confirm(candidate) → принять результат
+    // - skip() → пометить как manual-review-needed
+}
+```
+
+**Статус**: под вопросом — оценить объём работ перед реализацией. Возможно проще оставить Hermes cron как оркестратор но дать ему доступ к graph facts через `--format json`.
 
 **Цель:** найти реальную структуру медиабиблиотеки, где симлинки, куда ведут.