docs_content/free_analysis.md

Свободный анализ

Что это такое

Свободный анализ сейчас означает ANALYZE через agent-only runtime.

Бот не выбирает заранее написанную custom family. Вместо этого он:

  • понимает вопрос через coarse classification;
  • запускает agent-а;
  • даёт agent-у инструменты get_catalog и query_data;
  • выполняет внутренние safe FACT-запросы через общий planner/executor;
  • возвращает итоговый Telegram HTML ответ.

Что важно

  • Agent не пишет произвольный SQL.
  • Все запросы к данным идут через query_data.
  • query_data использует те же ограничения, что обычный FACT.
  • Agent может сделать несколько запросов, если ему нужно сравнить периоды, сегменты или метрики.
  • Финальные выводы строятся поверх реально полученных строк.

Какие аналитические паттерны стоит спрашивать

Agent должен покрывать такие классы вопросов:

  • вероятность оплаты и ожидаемые оплаты;
  • сегменты с плохим ROMI, высоким расходом или дорогими лидами;
  • сравнение подрядчиков, каналов, воронок, кампаний и объявлений;
  • просадки ROMI, CPL, конверсии и выручки;
  • рекомендации по перераспределению бюджета;
  • диагностика узкого места воронки;
  • общий обзор аномалий и зон риска.

Это больше не отдельные hard-coded handlers. Это пользовательские паттерны, которые agent обрабатывает через общий tool loop.

Как лучше формулировать вопросы

Лучше всего явно указывать:

  • период;
  • нужный срез: подрядчик, канал, воронка, кампания, объявление, utm_source;
  • метрики или критерий: ROMI, CPL, расход, лиды, оплаты, выручка;
  • что именно нужно получить: сравнить, найти просадку, выбрать кандидатов на сокращение, оценить вероятность.

Примеры:

  • Какие подрядчики убыточны по ROMI за 14 дней
  • Где высокий бюджет и низкий ROMI по воронкам за 14 дней
  • Куда перераспределить бюджет по подрядчикам за 30 дней
  • Где ROMI резко упал по каналам за 7 дней
  • Оцени вероятность оплаты по воронке фдк26 за 3 месяца
  • Где узкое место по воронке фдк26 за 14 дней

Как читать ответ

Agent должен возвращать ответ в структуре:

  1. Рекомендации — что делать и по каким критериям.
  2. Данные — конкретные строки и числа.
  3. Параметры — период, тип даты, атрибуция и другие фактически применённые настройки.

Числа в блоке Данные важнее нарратива. Если текстовая рекомендация кажется спорной, сверяйтесь с таблицей и параметрами запроса.

Текущие ограничения

  • Нет произвольного SQL.
  • Нет произвольных пользовательских формул.
  • Нет гарантии, что agent каждый раз выберет ровно тот же набор внутренних запросов.
  • Нет отдельной deterministic family для каждого сценария.
  • Длинные широкие вопросы могут упереться в token/cost/timeout budget.

Как это тестировать

Для regression testing нужны:

  • unit-тесты analysis.tools;
  • unit-тесты analysis.agent;
  • service tests с mocked run_analysis;
  • golden-примеры на реальные пользовательские формулировки;
  • прод-наблюдение через botops_queries, botops_incidents, feedback.