ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Реализация partial harnessing для AI-агента

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

Научиться проектировать механизм Harnessing|partial harnessing — когда системе выдаётся только начало плана (первые 2 шага), а агент (LLM) должен самостоятельно достроить и выполнить оставшиеся шаги для достижения цели. Задача имитирует реальный сценарий, где агент получает неполную инструкцию и вынужден действовать автономно.

Ключевой результат Рабочий harness, который принимает задачу и первые 2 шага плана, запускает агента, который завершает остальные шаги, и возвращает итоговый результат в рамках заданных критериев успеха.

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

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

1. Использовать локальную модель (Ollama с llama3.2:3b) — достаточно для демонстрации.
2. Написать заглушку LLM, которая возвращает предопределённые шаги на основе входящего контекста — но это упрощение. Лучше использовать реальную модель с ограниченным контекстом.

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

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

Этап 1: Проектирование структуры partial plan и harness (1 час)

Действия

1. Определить формат плана
   Разработать Pydantic-модель PartialPlan, которая содержит:

   • task_description: str — полное описание задачи.
   • initial_steps: List[Вики/step_number|Step — первые 2 шага (с номером, описанием, ожидаемым результатом).
   • total_steps_count: int — общее количество шагов (агент должен додумать total_steps_count - len(initial_steps) шагов).

   Пример модели:

   from pydantic import BaseModel
   from typing import List
   
   class Step(BaseModel):
       number: int
       description: str
       expected_outcome: str = ""
   
   class PartialPlan(BaseModel):
       task: str
       initial_steps: List[Step]  # первые 2 шага
       total_steps: int           # всего шагов (>=2)
   

2. Спроектировать интерфейс harness’а
   Harness должен:

   • Принимать PartialPlan.
   • Выполнять шаги 1 и 2 (через call|вызов LLM / внешние инструменты).
   • После выполнения первых двух шагов вызывать LLM-агента с контекстом “Выполнены шаги 1 и 2. Придумай и выполни оставшиеся шаги для завершения задачи. Учитывай, что уже сделано.”
   • Агент генерирует последующие шаги в том же формате и выполняет их.
   • Возвращать итоговый ответ.

3. Создать директорию проекта и репозиторий Git.

   mkdir partial-harness && cd partial-harness
   git init
   

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

• Файл models.py с Pydantic-моделями.
• Прототип интерфейса harness’а (заглушка или класс PartialHarness).

Этап 2: Реализация ядра harness’а (2 часа)

Действия

1. Написать класс PartialHarness

   • Конструктор принимает LLM-клиента (например, ChatOpenAI), опционально инструменты.
   • Метод execute(plan: PartialPlan) -> str.
   • Логика:
     1. Валидировать план (первые шаги не пустые, total_steps >= len(initial_steps)).
     2. Выполнить первые шаги:
        • Для каждого шага вызвать LLM с инструкцией “Ты выполняешь шаг X: {description}. Ожидаемый результат: {expected_outcome}. Предыдущие результаты: {контекст}”.
        • Сохранить результаты выполненных шагов как строку executed_context.
     3. Сформировать промпт для агента-продолжателя:

        Задача: {task}
        Выполненные шаги (первые {n} из {total}):
        Шаг 1: {description} -> {result}
        Шаг 2: {description} -> {result}
        
        Теперь придумай и выполни оставшиеся шаги (с шага 3 по шаг {total}). 
        Для каждого шага опиши его и верни результат. Итоговый ответ должен соответствовать задаче.
        

     4. Вызвать LLM для генерации и выполнения остальных шагов. Рекомендуется сделать цикл: агент генерирует по одному шагу и выполняет его, пока не достигнет total_steps или не решит, что задача завершена.
     5. Собрать полный лог выполнения и вернуть финальный результат.

2. Интегрировать логирование
   Каждый шаг должен логировать: номер, описание, результат, время выполнения.

3. Написать unit-тесты для моделей и базовой логики harness’а.
   Проверить, что валидация плана работает, что пустой список шагов вызывает ошибку.

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

• Файл harness.py с классом PartialHarness (метод execute).
• Файл test_harness.py с 3-4 тестами (проверка валидации, выполнение первых шагов на заглушке LLM).

Этап 3: Создание тестовой задачи и интеграция (1 час)

Действия

1. Выбрать конкретную задачу для демонстрации
   Пример: “Напиши Python-функцию fibonacci(n: int) -> int, которая возвращает n-е число Фибоначчи. Используй рекурсивный подход с мемоизацией.”
   Разбить задачу на 5 шагов:

   • Шаг 1: Определить сигнатуру функции.
   • Шаг 2: Реализовать рекурсивную функцию без мемоизации (заглушка).
   • Шаг 3: Добавить кэш (декоратор functools.lru_cache или словарь).
   • Шаг 4: Написать тестовый вызов (assert).
   • Шаг 5: Вернуть код функции + краткое объяснение.

2. Создать файл example_task.py, где задана эта задача и правильные шаги (для сравнения).

3. Запустить harness с partial-планом (первые 2 шага).

   • Убедиться, что LLM-агент генерирует шаги 3-5 (возможно, с небольшими вариациями).
   • Проверить итоговый код на синтаксис и корректность (запустить в exec или импорте).

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

• Harness успешно обрабатывает задачу и возвращает рабочий код функции.
• Лог выполнения сохранён в файл execution_log.json.

Этап 4: Тестирование на нескольких задачах и оценка (1.5 часа)

Действия

1. Подготовить 3 задачи разной сложности

   • Задача A (как выше): написать функцию.
   • Задача B: “Найди максимальное число в списке и верни его индекс.”
   • Задача C: “Создай JSON-схему для каталога книг (поля: title, author, year, isbn).”

2. Для каждой задачи задать частичный план (только первые 2 шага).

3. Запустить harness и записать результаты

   • Если агент не завершает задачу (например, циклит или генерирует бессмысленный код) – это считается неудачей.

4. Оценить метрики успеха

   • Completion rate: процент задач, где агент выдал валидный результат (проверяется через тесты/валидацию).
   • Average number of steps generated: среднее количество шагов, додуманных агентом.
   • Deviation from expected plan: сколько шагов отличаются от эталонного плана (ручная проверка).
   • Time per task: среднее время выполнения.

5. Написать отчёт в markdown results.md с таблицей результатов.

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

• Файл results.md с таблицей по 3 задачам (название, completion, кол-во шагов, отклонения).
• Рекомендации по улучшению harness’а (например, добавить few-shot примеры в промпт).

Этап 5: Ретроспектива и улучшение (30 минут)

Действия

1. Проанализировать ошибки

   • В каких задачах агент отклонился от плана? Почему?
   • Какие добавления в промпт могли бы помочь?

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

3. Перезапустить тесты и сравнить метрики с предыдущими.

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

• Обновлённая версия harness.py с улучшениями.
• Секция “Improvements” в results.md.

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

• PartialPlan корректно сериализуется/десериализуется из JSON.
• Harness выполняет первые два шага, не изменяя их описания.
• Агент генерирует и выполняет как минимум 2 дополнительных шага (если total_steps >= 4).
• Итоговый результат задачи соответствует ожидаемому (проверяется через автоматический тест).
• Лог выполнения содержит информацию о каждом шаге (номер, описание, результат).
• Код покрыт тестами (минимум 4 теста: валидация, выполнение с заглушкой, интеграционный тест с реальной LLM).
• Проект хранится в Git с осмысленными коммитами.
• results.md содержит результаты по 3 задачам и выводы.

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

Основной артефакт — кодовая база partial-harness/ со следующей структурой:

partial-harness/
├── models.py             # Pydantic модели
├── harness.py            # PartialHarness класс
├── example_task.py       # Пример задачи и правильные шаги
├── test_harness.py       # Unit/интеграционные тесты
├── execution_log.json    # Лог последнего запуска
├── results.md            # Отчёт по 3 задачам
├── requirements.txt      # Python зависимости
└── README.md             # Краткое описание задачи

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

• В results.md таблица с метриками (completion rate, steps, время).
• Пример успешного выполнения для задачи A (код функции).

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

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

Примечание Для первого запуска с реальным API рекомендуется увеличить бюджет до 8 ч (включая отладку промптов).

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

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

• Я убедился, что PartialPlan можно загрузить из JSON и он содержит ровно 2 шага.
• Я запустил harness хотя бы с одной задачей и получил финальный ответ.
• Я проверил, что первые два шага выполнены так, как я задал, а не изменены агентом.
• Я протестировал ситуацию, когда агент генерирует неверный результат — есть ли fallback?
• Я задокументировал все зависимости (requirements.txt) и инструкцию по запуску в README.md.