ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Настроить trajectory coverage для агентов

1. Цель задачи

Научиться собирать и анализировать траектории действий AI-агента, чтобы оценить полноту тестового покрытия. Разработать пайплайн логирования траекторий, построить метрики покрытия (например, долю уникальных траекторий, покрытых тестами) и подготовить отчёт с рекомендациями по расширению тестов.

Ключевой результат Рабочий скрипт анализа покрытия траекторий и отчёт (HTML/PDF/документ) с выявленными пробелами в тестировании.

2. Исходные данные

Перед началом необходимо иметь:

Если нет реального инструмента — симулируем:

1. Создать простого агента с 3–4 инструментами (поиск, калькулятор, дата-тайм, эхо).
2. Запустить агента на 20–30 тестовых запросах, логируя каждый шаг (вызов инструмента + результат) в JSON.
3. Полученные логи считать «производственными». Дополнительно вручную написать 5 «идеальных» траекторий — они будут эталоном для оценки покрытия.

3. Технологический стек

4. Этапы выполнения

Этап 1: Логирование траекторий (1–2 часа)

Действия

1. Добавить в агента логгер шагов Каждый вызов инструмента или LLM фиксировать с полями:

   • session_id (уникальный идентификатор диалога)
   • step_number (порядковый номер шага)
   • action (название инструмента или типа LLM)
   • input (аргументы инструмента / запрос)
   • output (результат инструмента / ответ LLM)
   • timestamp

   Пример структуры лога:

   {
     "session_id": "abc123",
     "step_number": 1,
     "action": "search_web",
     "input": {"query": "погода Москва"},
     "output": "Солнечно, +15°C",
     "timestamp": "2025-04-01T10:00:00Z"
   }
   

2. Настроить запись логов в файл
   Имя файла: trajectories_<date>.jsonl (по одной строке JSON на шаг).

3. Запустить агента на 20–30 разнообразных запросах (включая ошибки, неоднозначности, повторные попытки).
   — Убедиться, что все шаги записаны.

Ожидаемый результат этапа Набор лог-файлов JSONL с минимум 100 шагов от 20+ сессий.

Этап 2: Сбор и нормализация данных (1 час)

Действия

1. Загрузить логи в pandas DataFrame
   Каждый шаг — строка. Сгруппировать по session_id и отсортировать по step_number.

2. Построить последовательность действий для каждой сессии.
   Пример: ['search_web', 'llm_reasoning', 'calculator', 'final_answer']

3. Удалить избыточные шаги (повторные запросы одного и того же инструмента без изменения контекста), если они не влияют на покрытие.

4. Нормализовать названия действий (привести к единому регистру, объединить синонимы).
   Составить словарь нормализации.

Ожидаемый результат этапа DataFrame с колонками:

• session_id, trajectory (список действий), length, outcome (успех/ошибка/частично).

Этап 3: Анализ покрытия траекторий (2 часа)

Действия

1. Определить эталонные траектории
   Вручную написать 5–10 траекторий, которые агент должен уметь выполнять (например, для вопроса «сколько времени в Нью-Йорке?» траектория: [current_datetime, timezone_conversion, final_answer]).

2. Рассчитать метрики покрытия

   • Уникальные траектории количество разных последовательностей действий среди логов.
   • Edge coverage какая доля рёбер (переходов между последовательными действиями) из «полного графа» покрыта.
   • Path coverage какая доля эталонных траекторий встречается хотя бы один раз в логах.
   • Frequency coverage топ-5 самых частых траекторий – какую долю запросов они покрывают.

   Код для расчёта edge coverage:

   def edge_coverage(logs_trajectories):
       edges = set()
       all_possible_edges = set()
       for traj in logs_trajectories:
           for i in range(len(traj)-1):
               edges.add((traj[i], traj[i+1]))
       # Допустим, все возможные рёбра известны из полного списка действий
       all_actions = list(set([a for traj in logs_trajectories for a in traj]))
       for a in all_actions:
           for b in all_actions:
               all_possible_edges.add((a, b))
       return len(edges) / len(all_possible_edges) if all_possible_edges else 0
   

3. Выявить пробелы
   — Какие эталонные траектории отсутствуют?
   — Какие редкие или «опасные» последовательности не протестированы (например, ошибка → повтор → отказ)?

Ожидаемый результат этапа Числовые метрики покрытия и список непокрытых траекторий.

Этап 4: Визуализация и отчёт (1–2 часа)

Действия

1. Построить граф траекторий (networkx + plotly): узлы — действия, рёбра — переходы, толщина ребра — частота встречаемости.

2. Создать дашборд в Jupyter Notebook
   — Таблица метрик покрытия.
   — График частот траекторий (топ-10).
   — Heatmap переходов для выявления зацикливаний.
   — Список эталонных траекторий с пометкой «покрыта»/«не покрыта».

3. Написать текстовый отчёт с выводами:

   • Общее количество уникальных траекторий.
   • Процент покрытия рёбер и путей.
   • Самые частые траектории.
   • Рекомендации по добавлению тестов (какие траектории нужно протестировать).

Ожидаемый результат этапа

• Jupyter Notebook (.ipynb) с интерактивными графиками.
• Отчёт в формате Markdown или PDF (экспорт из Notebook).

Этап 5 (опционально): Улучшение покрытия (1–2 часа)

Действия

1. Написать 10–15 новых тестов для непокрытых траекторий (используя pytest + агент в режиме симуляции).
2. Повторно запустить анализ покрытия — убедиться, что метрики улучшились.
3. Документировать процесс как поддерживать покрытие на заданном уровне.

Ожидаемый результат этапа Набор дополнительных тестов и обновлённый отчёт с улучшенными метриками.

5. Критерии приемки (Definition of Done)

• Реализовано логирование каждого шага агента (действие, вход, выход).
• Собран датасет из минимум 20 сессий с полными траекториями.
• Код анализа покрытия оформлен в виде Python модуля или скрипта.
• Рассчитаны минимум 3 метрики покрытия: уникальные траектории, edge coverage, path coverage (по эталонам).
• Построен граф переходов с визуализацией.
• Сгенерирован отчёт (Jupyter Notebook + Markdown/PDF) с выводами.
• Отчёт содержит не менее 5 рекомендаций по добавлению тестов.
• Воспроизводимость: при повторном запуске на тех же логах метрики совпадают.
• Код покрыт docstring и аннотациями типов (опционально).
• Проведено ревью кода внутри команды (имитация).

6. Ожидаемый результат

Основной артефакт Python-пакет или Jupyter Notebook с названием trajectory_coverage_analysis и содержимым:

• logger.py – кастомный логгер для агента.
• collector.py – сбор и нормализация логов.
• analyzer.py – расчёт метрик покрытия.
• visualizer.py – построение графов и heatmap.
• report_template.md – шаблон отчёта.
• example_data/ – демонстрационные логи (JSONL).

Дополнительно

• Набор из 10 эталонных траекторий.
• Инструкция по интеграции логгера в существующего агента.
• Пример использования: python run_analysis.py --logs logs/ --refs refs.json --output report.html

7. Возможные сложности и их решение

8. Бюджет времени (оценка)

Примечание: Для первого раза заложить +1 час на отладку логгера и +1 час на поиск ошибок в анализе.

9. Связанные вопросы из базы знаний

10. Чек-лист самопроверки

• Я добавил логгер, который записывает каждый шаг с session_id, действием, входом и выходом.
• Я собрал не менее 20 сессий и проверил, что нет сессий без шагов.
• Я написал скрипт, который загружает логи и строит последовательности действий.
• Я определил эталонные траектории (минимум 5) и сравнил их с реальными.
• Я рассчитал минимум три метрики: количество уникальных траекторий, edge coverage, path coverage.
• Я построил визуализацию графа переходов и heatmap.
• Я сформулировал не менее 5 конкретных рекомендаций по добавлению тестов.
• Я убедился, что отчёт можно воспроизвести (запуск скрипта на тех же данных даёт те же результаты).
• Я закоммитил весь код, данные и отчёт в git-репозиторий с README.