MICROFLUIDICS.md

CoScientist — профиль «Микрофлюидика»

Отдельная конфигурация CoScientist для кейса микрофлюидики: разработка веществ (например, ПАВ) с получением целевых молекул на проточном / микрофлюидном реакторе. Из полной системы оставлены только оркестратор с планером и анализ литературы; добавлен агент постановки ТЗ, портированный из проекта VibePAV (VibePAV/).

Пайплайн

Каждый запрос в этом деплойменте — кейс микрофлюидики, поэтому стадия ТЗ выполняется детерминированно ПЕРЕД планированием:

запрос заказчика
  └─ InitAgent (sequential)
       ├─ TZAgent (sequential)                        ← порт VibePAV
       │    ├─ TZSpecAgent      → state["structured_tz"]          таблица ТЗ
       │    └─ TZQueryGenAgent  → state["tz_literature_queries"]  LIT-01…LIT-06
       ├─ PlannerAgent          → create_plan: одна задача на каждый LIT-запрос
       └─ OrchestratorAgent     → делегирует LIT-задачи ResearchAgent,
                                  собирает финальный отчёт по ТЗ

• TZSpecAgent — превращает свободный запрос в структурированный документ ТЗ формата эталонного примера (CoScientist/microfluidics/Пример_уточненного_структурированного_ТЗ_для_агентов.md): 16 канонических блоков (тип задачи, целевой продукт, область применения, требуемые свойства, критерии качества, масштаб, ограничения по сырью/поставкам/себестоимости/технологии, оборудование, аналитика, данные заказчика, безопасность, приоритеты, форма результата), каждый блок — таблица конкретных полей «Поле | Значение | Статус». Схема: CoScientist/microfluidics/models.py::StructuredTZ (блоки → поля); человекочитаемый Markdown-документ рендерится детерминированно (render.py::render_tz_document): правила интерпретации статусов, исходный запрос, обзорная таблица, таблицы блоков, незаполненные поля, проверка по опроснику. Документ сохраняется в state["structured_tz_document"] и в файл tz_documents/TZ_<timestamp>.md; в HITL-ревью оператор видит именно этот документ, а не JSON. После принятия ТЗ (перед переходом к планированию и поиску литературы) агент публикует документ в чат — сообщением с путём к файлу и полным текстом; открыть последний документ в браузере: GET /api/tz-document (конкретный файл — ?name=TZ_<timestamp>.md).
• TZQueryGenAgent — из ТЗ формирует 4–6 точечных поисковых задач (id, task, query_en, extract) — это и есть структурированная информация о том, что именно запрашивать у агента анализа литературы.
• PlannerAgent получает ТЗ и запросы через инъекции состояния ({structured_tz?}, {tz_literature_queries?}) и регистрирует план: одна задача на LIT-запрос, assignee ResearchAgent, query_en — дословно в описании задачи.
• OrchestratorAgent исполняет план, передавая query_en и список извлекаемых данных в ResearchAgent (websearch + papers_search + paper_analysis), затем собирает отчёт по структуре ТЗ.

Запуск отдельного инстанса

Профиль выбирается переменной окружения COSCIENTIST_CONFIG (имя профиля → CoScientist/agents/<имя>.yaml, либо путь к YAML):

# веб-интерфейс на отдельном порту (по умолчанию 8010) — можно поднимать
# параллельно с основным CoScientist на 8000
python scripts/run_microfluidics_web.py

# без человека (headless-режим для тестирования — HITL полностью выключен)
python scripts/run_microfluidics_web.py --no-hitl

# или вручную:
COSCIENTIST_CONFIG=microfluidics COSCIENTIST_WEB_PORT=8010 python CoScientist/web/server.py

# валидация конфигурации (без LLM-вызовов)
COSCIENTIST_CONFIG=microfluidics python -m CoScientist.assembly

Human-in-the-loop (ревью оператора)

Аналог интерактивного опросника VibePAV: обе стадии ТЗ и планер — session-агенты с циклом ревью. Агент предлагает артефакт, человек одобряет или присылает правки, агент переделывает до одобрения:

1. TZSpecAgent — таблица ТЗ (можно дополнить недостающие блоки — они получат статус «уточнено оператором»);
2. TZQueryGenAgent — литературные запросы LIT-xx;
3. PlannerAgent — план;
4. ResearchAgent — точечные подтверждения дорогих действий (request_approval).

В веб-UI запрос ревью — карточка в чате: заголовок, текст предложения агента (документ ТЗ / JSON запросов, прокручиваемый блок), поле для правок и кнопки Accept (принять как есть), Revise (отправить правки — агент перепишет результат с их учётом) и Reject. Внимание: без ответа оператора запрос авто-подтверждается через 5 минут (WebHITLHandler.HITL_TIMEOUT_SECONDS). В CLI — консольное меню.

Опросник оператора (порт опросника VibePAV) — по одному окну на вопрос

Ревью ТЗ двухфазное:

1. Согласование документа. Показывается отрендеренный документ ТЗ с заметкой, сколько блоков осталось незаполненными. Accept — согласовать и перейти к опросу; Revise — правки к самому документу (перегенерация).
2. Опрос — одно HITL-окно на один вопрос. По каждому блоку с полями «не задано» приходит отдельная карточка (вопрос K из N, формулировка и подсказка из опросника VibePAV, список незаполненных полей) с кнопками:
   • Ответить — вписать ответ в поле (значение получит статус «уточнено оператором»);
   • «Не знаю — пропустить» — поля останутся «не задано», система продолжит без них;
   • «На усмотрение агента» — агент подставит рабочее значение из отраслевого контекста;
   • «Завершить опрос» — пропустить все оставшиеся вопросы.

Собранные ответы вносятся в ТЗ одним переписыванием, обновлённый документ приходит на финальное согласование, после чего публикуется и пайплайн идёт дальше. Опрос выполняется один раз на запрос; два подряд неотвеченных вопроса (авто-таймауты по 300 с) завершают опрос автоматически — застрять невозможно.

Диагностика, если вопросы «не приходят». Откройте GET /api/hitl-status — там видно: включён ли HITL, привязан ли websocket, какие агенты подключены и какие запросы ревью ждут ответа. Жизненный цикл каждого запроса пишется в logs/app.log (логгер CoScientist.web.hitl): отправка в браузер, ответ или HITL TIMEOUT … AUTO-APPROVING (через 300 с без ответа пайплайн продолжается автоматически — об этом придёт системное сообщение в чат). При переподключении вкладки неотвеченные запросы ревью доставляются повторно; страница отдаётся с Cache-Control: no-store, чтобы браузер не держал старый фронтенд. После обновления кода перезапускайте сам процесс сервера — кнопка Stop в UI сбрасывает только сессию, не код.

Отключение для тестирования без человека — один переключатель:

HITL__ENABLED=false            # env или .env — циклы ревью проходят насквозь
python scripts/run_microfluidics_web.py --no-hitl   # то же самое для веба

Точечно HITL отключается на конкретном агенте через hitl: false в microfluidics.yaml.

Тесты

# структурные (без LLM): сборка профиля, ТЗ-стадия первая, промпты согласованы
pytest tests/unit/test_microfluidics_assembly.py -q

# живой e2e: запрос → таблица ТЗ → план → проверка, что в ResearchAgent
# приходит запрос, выведенный из ТЗ (нужны .env и сеть; HITL отключается)
pytest tests/integration/test_microfluidics_e2e.py -q -s

# живой тест HITL-цикла ТЗ-стадии: скриптованный «оператор» шлёт правку (EDIT),
# агент переписывает таблицу; плюс headless pass-through
# (запускать ОТДЕЛЬНЫМ вызовом pytest от e2e — настройки HITL фиксируются на процесс)
pytest tests/integration/test_microfluidics_hitl.py -q -s

Файлы профиля

Файл	Назначение
CoScientist/agents/microfluidics.yaml	декларация системы (профиль)
CoScientist/microfluidics/models.py	StructuredTZ, LiteratureQuery (порт VibePAV)
CoScientist/agents/prompts/templates.py	промпты microfluidics_*
scripts/run_microfluidics_web.py	запуск отдельного веб-инстанса