NODEDC_1C/IN/TZ_LLM_Normalizer_v1.md

TZ_LLM_Normalizer_v1.md

Ниже даю жёсткое ТЗ для Codex на точечную доводку LLM-normalizer с очень экономным режимом прогонов.

---

ТЗ для Codex: точечная доводка LLM Normalizer v1 → v1.1

1. Цель этапа

Довести текущий LLM-normalizer до более стабильного качества на реальных бухгалтерских человеческих запросах, не раздувая бюджет на API-прогоны.

Главная цель этапа:

• поднять качество нормализации;
• убрать текущие semantic-промахи по intent_class, route_hint и causal flags;
• сохранить 100% schema validation;
• сделать это через точечные изменения prompt/few-shot/eval, без массовых дорогих прогонов.

---

2. Текущий статус

Текущий eval дал:

• schema_validation_pass_rate = 100
• intent_class_accuracy = 72.73
• route_hint_accuracy = 90.91
• causal_flag_accuracy = 81.82
• high_confidence_error_rate = 9.09

Проблемные кейсы:

• NQ-004
• NQ-008
• NQ-009

Тип проблемы:

• schema уже держится хорошо;
• route_hint уже близок к рабочему;
• основное слабое место — intent_class;
• часть ошибок связана с неправильной трактовкой causal/cross-entity языка;
• минимум один кейс даёт ошибку route при при этом пойманной causal-семантике.

---

3. Главный принцип этапа

Очень важно

Не делать дорогую “перестрелку запросами”.

Нельзя:

• гонять большие автоматические sweep’ы;
• отправлять много повторов на один и тот же кейс;
• делать temperature-sampling по 10–20 вариантов;
• прогонять сотни запросов на каждую мелкую правку.

Нужно:

• сделать точечную forensic-доработку;
• разобрать 3 проблемных кейса;
• внести минимальные, но сильные изменения;
• прогнать ровно один запрос на кейс в контрольном eval-наборе;
• максимум 30 запросов на финальный контроль.

---

4. Budget constraints / лимиты на прогоны

Codex обязан соблюдать жёсткий лимит.

Допустимый лимит API-вызовов на этот этап

• до 10 вызовов на forensic/ручную проверку;
• до 30 вызовов на финальный eval-run;
• итого целевой потолок: не более 40 внешних LLM-запросов на весь этап.

Правила

1. Один кейс = один запрос.

2. Не делать повторные запросы на тот же кейс без явной необходимости.

3. Ретраи разрешены только:

   • при техническом fail,
   • при невалидном JSON,
   • не более 1 повтора на кейс.

4. Не делать random sampling.

5. temperature = 0 на всех eval-запусках.

6. Не делать “прогоны для красоты” после достижения приемлемого результата.

---

5. Что нужно сделать по шагам

Этап A. Forensic-аудит проблемных кейсов

Задача A1

Разобрать вручную кейсы:

• NQ-004
• NQ-008
• NQ-009

Что нужно собрать по каждому кейсу

Для каждого кейса составить мини-таблицу:

• case_id
• raw_question
• expected.intent_class
• actual.intent_class
• expected.route_hint
• actual.route_hint
• expected.requires
• actual.requires
• какие признаки модель не увидела
• какие признаки модель увидела лишние
• предполагаемая причина ошибки
• какая минимальная правка должна это исправить

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

Файл: docs/normalizer_forensic_audit_v1_1.md

Ограничение по вызовам

Новые API-вызовы для этого этапа делать только если не хватает уже существующих trace/result-данных. Цель: по возможности 0 новых запросов, максимум 3.

---

Этап B. Точечная доработка taxonomy и route logic в prompt-слое

Задача B1

Уточнить developer prompt так, чтобы он:

• жёстче различал:

  • cross_entity
  • anomaly_probe
  • rule_based_account_control
  • drilldown_explain
  • ambiguous_human_query

• не сваливал causal cross-entity в соседние классы.

Задача B2

Добавить/исправить правила приоритетов:

Приоритет 1

Если вопрос требует связать:

• документы,
• оплаты,
• проводки,
• закрывающие,
• договоры,
• регистры,
• даты,
• подтверждение цепочки,

то это не simple_factual и обычно не store_feature_risk, а causal multi-entity scenario.

Приоритет 2

Если вопрос про множество кейсов, даже если просит “объяснить”, это не needs_exact_object_trace, если нет одного конкретного документа/проводки/объекта.

Приоритет 3

Если в вопросе есть риск/аномалия-лексика, но одновременно есть document/payment/posting chain, то приоритет у causal cross-entity semantics, а не у risk-bucket.

Приоритет 4

ambiguous_human_query использовать только когда вопрос действительно не раскладывается в конкретный intent-class, а не как ленивый fallback.

Задача B3

Уточнить domain prompt:

• расширить словарь фраз:

  • “не бьётся”
  • “не сходится”
  • “не видно”
  • “не собралось”
  • “повисло”
  • “хвост”
  • “разложи по документам / оплатам / закрывающим”
  • “чем подтверждается”
  • “где ошибка в цепочке”
  • “что пошло криво”

• привязать их к causal semantics.

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

Обновить:

• prompts/developer/normalizer_v1_1.txt
• prompts/domain/normalizer_domain_v1_1.txt

---

Этап C. Few-shot patch вместо большого переписывания

Задача C1

Не переписывать весь prompt заново. Добавить только 5–7 новых few-shot примеров, которые закрывают пограничные случаи.

Обязательные типы новых few-shot

Нужно минимум по одному примеру на каждый паттерн:

1. cross_entity vs anomaly_probe
2. cross_entity vs rule_based_account_control
3. cross_entity multiple explain vs drilldown_explain
4. causal human language + risk words
5. ambiguous human wording, которое всё равно надо класть в нормальный intent-class
6. rule-based control без causal chain
7. heavy overview без точечного explain

Требование

Few-shot должны быть короткими. Не делать огромные простыни.

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

Обновить:

• prompts/fewshot/normalizer_fewshot_v1_1.txt

---

Этап D. Ужесточить confidence policy

Задача D1

Снизить долю high-confidence ошибок.

Что нужно сделать

Добавить в developer prompt правило:

Модель не должна ставить:

• confidence.overall = high
• confidence.route_hint = high

если одновременно:

• есть ambiguity,
• route зависит от тонкого различия между соседними классами,
• вопрос длинный и многослойный,
• модель не уверена в period scope,
• causal semantics частично восстановлена, но не полностью.

Цель

Снизить high_confidence_error_rate.

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

Правка внутри:

• developer prompt
• опционально: post-validation rule на backend, который помечает suspicious confidence

---

Этап E. Подготовить экономный eval-набор из 30 кейсов

Задача E1

Собрать один контрольный eval-набор: eval_cases/normalizer_eval_v1_1_30cases.json

Размер

Ровно 30 кейсов, не больше.

Ограничение

Один кейс = один запрос.

Состав набора

Сделать сбалансированно:

• cross_entity — 10 кейсов
• heavy_analytical — 5 кейсов
• drilldown_explain — 5 кейсов
• rule_based_account_control — 5 кейсов
• anomaly_probe / ambiguous_human_query / period_close_risk — 5 кейсов

Обязательные условия

• включить NQ-004, NQ-008, NQ-009 в переработанном виде или их исходные кейсы;
• включить минимум 5 человеческих формулировок из creative-stress стиля;
• не делать дубли почти одинаковых вопросов.

---

Этап F. Сделать один контрольный прогон

Задача F1

Запустить один eval-run по 30 кейсам.

Правила прогона

• temperature = 0

• один запрос на кейс

• без multi-sampling

• без повторов, кроме:

  • технического fail
  • invalid JSON

• максимум 1 retry на кейс

Ожидаемый файл отчёта

reports/normalizer_eval_v1_1_run.md

Ожидаемый JSON

reports/normalizer_eval_v1_1_run.json

---

6. Что нужно измерять в финальном отчёте

В отчёт обязательно вывести:

• cases_total
• schema_validation_pass_rate
• intent_class_accuracy
• route_hint_accuracy
• causal_flag_accuracy
• high_confidence_error_rate

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

• accuracy по каждому классу:

  • cross_entity
  • heavy_analytical
  • drilldown_explain
  • rule_based_account_control
  • anomaly_probe

• список всех mismatch’ов

• короткий комментарий по каждому mismatch’у

• сравнение до / после относительно текущих baseline-метрик

---

7. Целевые метрики этапа

Ниже не “идеальный мир”, а реальные целевые ориентиры.

Минимально приемлемо

• schema_validation_pass_rate >= 95
• intent_class_accuracy >= 85
• route_hint_accuracy >= 92
• causal_flag_accuracy >= 88
• high_confidence_error_rate <= 7

Хороший результат

• schema_validation_pass_rate >= 98
• intent_class_accuracy >= 88
• route_hint_accuracy >= 94
• causal_flag_accuracy >= 90
• high_confidence_error_rate <= 5

Отличный результат

• schema_validation_pass_rate = 100
• intent_class_accuracy >= 90
• route_hint_accuracy >= 95
• causal_flag_accuracy >= 92
• high_confidence_error_rate <= 3

Важно

Цель “95+ везде” можно держать как aspirational target, но Codex не должен ради этого устраивать дорогую перестрелку запросами. Сначала нужен максимально дешёвый и умный рост качества.

---

8. Что нельзя делать

Codex запрещено:

1. Делать массовый prompt sweep.
2. Прогонять десятки вариантов одного и того же кейса.
3. Использовать temperature > 0 для eval.
4. Делать скрытые повторные запросы “на всякий случай”.
5. Увеличивать eval set выше 30 кейсов без явной необходимости.
6. Пытаться лечить всё переписыванием backend-логики, если проблема решается prompt/few-shot таксономией.
7. Ломать уже рабочую schema validation ради intent tuning.

---

9. Что нужно поправить в коде

Codex должен проверить и при необходимости обновить:

A. Prompt manager

• версионирование prompt’ов:

  • normalizer_v1
  • normalizer_v1_1

• возможность быстро переключать presets

B. Eval runner

• добавить режим:

  • single-pass-strict

• который гарантирует:

  • один запрос на кейс,
  • без повторов,
  • лог явных retries

C. Report generator

• добавить сравнение baseline vs current
• отдельно выводить mismatch table
• отдельно выводить bad confidence cases

D. Storage / trace

• сохранить привязку:

  • case_id
  • trace_id
  • prompt_version
  • schema_version
  • model
  • request_count_for_case

Это нужно, чтобы контролировать бюджет реально.

---

10. Какие артефакты должен выдать Codex

Codex обязан выдать:

1. docs/normalizer_forensic_audit_v1_1.md

2. обновлённые prompt-файлы:

   • prompts/developer/normalizer_v1_1.txt
   • prompts/domain/normalizer_domain_v1_1.txt
   • prompts/fewshot/normalizer_fewshot_v1_1.txt

3. новый eval-набор:

   • eval_cases/normalizer_eval_v1_1_30cases.json

4. обновлённый экономный eval runner

5. отчёты:

   • reports/normalizer_eval_v1_1_run.md
   • reports/normalizer_eval_v1_1_run.json

6. краткий changelog:

   • docs/normalizer_v1_1_changes.md

---

11. Формат changelog

В changelog обязательно указать:

• что именно было изменено в prompt’ах;
• какие linguistic patterns добавлены;
• какие few-shot кейсы добавлены;
• какие кейсы были проблемными в baseline;
• сколько API-вызовов было потрачено на этап;
• итоговые метрики до/после;
• что осталось проблемным после тюнинга.

---

12. Приёмка этапа

Этап считается принятым, если одновременно выполнены условия:

1. Не превышен лимит внешних API-вызовов:

   • желательно до 40,
   • жёсткий потолок 45 только при техфейлах.

2. Есть forensic-аудит 3 проблемных baseline-кейсов.

3. Есть обновлённые prompt/few-shot файлы.

4. Есть новый eval-набор из 30 кейсов.

5. Есть один финальный eval-run.

6. Schema validation не просела.

7. route_hint_accuracy не стала хуже baseline.

8. intent_class_accuracy выросла заметно относительно baseline.

9. high_confidence_error_rate не вырос, а лучше — снизился.

10. В отчёте есть честный список оставшихся mismatch’ов.

---

13. Короткий practical summary для Codex

Что делать по сути:

1. Разобрать 3 плохих кейса.
2. Точечно усилить taxonomy и causal-language interpretation.
3. Добавить 5–7 сильных few-shot примеров.
4. Не трогать лишнего.
5. Собрать 30-кейсовый eval set.
6. Прогнать его одним проходом.
7. Сравнить с baseline.
8. Выдать отчёт и changelog.
9. Не жечь бюджет.

---

14. Самый важный акцент

Главная задача Codex сейчас — не сделать “идеальную исследовательскую систему”, а сделать дешёвую и умную доводку уже рабочего normalizer’а.

То есть нужно:

• чинить только то, что реально болит;
• не трогать то, что уже работает;
• не плодить дорогие прогоны;
• улучшать качество через forensic + prompt/few-shot patching.

---