# ТЗ для Codex — Validation Run по Accounting Analytics Layer, Orchestration и LLM-like Benchmark

## 1. Назначение документа

Документ фиксирует следующий этап работ после успешного подтверждения runtime semantic bridge к 1С.

Цель этапа:
- довести **жирный monthly slice** до полноценно посаженного аналитического слоя;
- провести **жёсткую верификацию онтологии и mapping-слоя**;
- формализовать **оркестрацию источников данных**;
- подготовить и выполнить **контролируемый benchmark-run** по набору бухгалтерских вопросов;
- выполнить этот benchmark **не на реальной 4o mini**, а через Codex в режиме максимально близкой эмуляции её поведения;
- получить подробный инженерный отчёт о качестве маршрутизации, скорости и полноте ответов.

---

## 2. Контекст

На предыдущих этапах подтверждено:
- runtime semantic bridge работает;
- read-only режим подтверждён;
- критические цепочки `document -> posting -> account`, `posting -> subconto[1..3]`, `saldo -> movements` доказаны;
- `1c-mcp-toolkit` принят со статусом `adopt with restrictions`;
- общая архитектура analytics layer спроектирована, но orchestration-service и насыщение store ещё не доведены до production-ready уровня.

Сейчас задача не в том, чтобы искать новый мост, а в том, чтобы:
1. проверить, что analytics-layer действительно сел на реальный жирный срез;
2. проверить, что ontology и mapping не врут;
3. задать правила оркестрации;
4. провести честный тест пользовательских вопросов.

---

## 3. Главная цель этапа

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

### Вопрос 1
Насколько качественно и полно **жирный месячный snapshot** садится в canonical/feature/risk слои?

### Вопрос 2
Насколько онтология и mapping-layer действительно покрывают:
- сущности 1С;
- взаимосвязи между ними;
- типизацию связей;
- критические бухгалтерские цепочки?

### Вопрос 3
Можно ли формализовать orchestration так, чтобы система:
- не делала лишних тяжёлых live-вызовов;
- не слала LLM в неправильные источники;
- умела различать простые, сложные, batch-heavy и drill-down сценарии?

### Вопрос 4
Как система ведёт себя на реальном наборе бухгалтерских вопросов по времени, маршруту и качеству ответа, если прогон имитирует поведение `4o mini` без фактического расхода дорогих токенов?

---

## 4. Общая задача для Codex

Codex должен выполнить полный цикл:

1. взять **один жирный monthly slice** как эталонный тестовый срез;
2. довести его до корректной посадки в canonical/feature/risk store;
3. провести **жёсткий ontology + mapping audit**;
4. формализовать orchestration policy;
5. подготовить benchmark-runner под список бухгалтерских вопросов;
6. выполнить benchmark-run в режиме **LLM-like simulation**, максимально приближенном к `4o mini`;
7. вернуть детальный инженерный отчёт.

---

## 5. Жирный slice — обязательный эталон

### Требование
Взять **один жирный месячный snapshot** как основной тестовый срез.

Текущий приоритет:
- июнь 2020, если именно он уже зафиксирован как наиболее объёмный и показательный.

### Что требуется по slice
- посадить его в canonical store полностью;
- посадить в feature store;
- прогнать через risk/anomaly слой;
- убедиться, что slice даёт не просто хранение, а реальный материал для аналитики.

### Что проверить
- количество сущностей;
- количество связей;
- количество типизированных связей;
- количество `Unknown` и иных деградированных target/source entity;
- сколько объектов попало в canonical;
- сколько признаков/feature записано;
- сколько anomaly/risk сигналов получилось;
- какие классы сущностей реально покрыты.

---

## 6. Жёсткая проверка онтологии и mapping

## 6.1. Цель
Провести взрослую верификацию ontology/mapping-слоя.

### Нельзя ограничиться:
- “сущности вообще есть”;
- “связи вообще есть”.

### Нужно проверить:
- корректна ли типизация сущностей;
- корректна ли типизация связей;
- насколько стабильно ложатся документы, проводки, счета, субконто, контрагенты, договоры, склады, номенклатура, регистры;
- насколько корректно разрешаются ссылки;
- нет ли систематических ложных сопоставлений;
- где ontology/mapping врёт.

## 6.2. Обязательные метрики ontology audit
Codex должен посчитать и отдать:
- общее число entity classes;
- число covered entity classes;
- число uncovered entity classes;
- число relation types;
- число корректно типизированных relations;
- число `Unknown` и аналогичных деградированных маппингов;
- число конфликтных mappings;
- процент link coverage;
- процент semantic coverage;
- список самых проблемных типов сущностей и связей.

## 6.3. Жёсткая цель
Онтология должна быть:
- переносимой;
- не привязанной к одной компании;
- пригодной для других 1С-контуров, как минимум того же класса;
- не собранной “под один snapshot вручную”.

---

## 7. Формализация оркестрации

## 7.1. Цель
Сформировать правила orchestration layer:
- что считается простым запросом;
- что считается drill-down запросом;
- что считается heavy analytical запросом;
- когда идти в OData;
- когда идти в MCP/runtime bridge;
- когда работать по snapshot/canonical store;
- когда использовать feature/risk/anomaly store;
- когда запускать batch refresh/analysis.

## 7.2. Источники, которые надо развести
Нужно развести по ролям:

### A. OData
Использовать как:
- discovery layer;
- быстрый широкий обзор структуры;
- fallback для типовых сущностей, если это быстрее и дешевле;
- лёгкий слой навигации.

### B. MCP / Runtime Bridge
Использовать как:
- live semantic bridge;
- drill-down;
- доступ к документу, проводке, счёту, subconto, saldo;
- точечные запросы;
- ситуации, когда нужен актуальный runtime truth.

### C. Snapshots / Canonical Store
Использовать как:
- основной слой для already-loaded истории;
- источник для быстрых аналитических ответов;
- источник для cross-period анализа;
- источник для вопросов, где не нужна свежесть в секунду.

### D. Feature / Risk / Anomaly Store
Использовать как:
- быстрый источник готовых аналитических выводов;
- anomaly-first ответы;
- risk-based маршрутизацию;
- summarized insight layer.

## 7.3. Обязательный результат
Codex должен оформить:
- **decision tree оркестрации**;
- список правил маршрутизации;
- источники по приоритету;
- fallback logic;
- timeout budget;
- max retrieval budget;
- политика retry/replan;
- политика отказа от неадекватно тяжёлых live-запросов.

---

## 8. LLM-like benchmark без реальной 4o mini

## 8.1. Главная идея
Нужно выполнить benchmark-run так, чтобы Codex **приблизил своё поведение к профилю `4o mini`**, но без реального расхода токенов OpenAI.

## 8.2. Важно
Это не “настоящая 4o mini”.
Это controlled emulation / simulation.

## 8.3. Требование к Codex
Codex должен надеть на себя **ограничения и поведенческие правила**, максимально похожие на рабочий режим дешёвой быстрой модели:

### Ограничения по мышлению и маршрутизации
- не уходить в бесконечную глубину;
- делать компактную декомпозицию вопроса;
- не генерировать чрезмерно сложные планы, если вопрос можно решить проще;
- отдавать предпочтение уже существующим store-layer ответам, если они достаточны;
- использовать live bridge только по необходимости;
- минимизировать число round-trips;
- минимизировать контекст;
- не строить “идеальную академическую” стратегию, если хватит практичной.

### Ограничения по ответу
- отвечать короче и практичнее;
- не делать длинных философских объяснений;
- давать инженерно полезный ответ;
- явно помечать, когда ответ построен на store, а когда на live data.

### Ограничения по стоимости / latency simulation
Codex должен действовать так, как будто:
- запрос дорогой;
- шаги надо экономить;
- retrieval budget ограничен;
- слишком тяжёлые запросы надо сворачивать или бить на этапы.

## 8.4. Что нужно получить
Не “магически стать 4o mini”, а:
- получить benchmark в **сравнимом дешёвом профиле рассуждения**.

---

## 9. Набор бухгалтерских вопросов

Codex должен прогнать набор **35 тестовых бухгалтерских вопросов**.

### Требования к набору
Вопросы должны быть:
- разношёрстные;
- от простых к тяжёлым;
- от конкретных к общим;
- от точечных к аналитическим;
- от single-object к whole-slice;
- покрывать разные маршруты системы.

### Классы вопросов
Нужно включить:

1. **Простые factual**
   - по документу;
   - по счёту;
   - по проводке;
   - по контрагенту;
   - по договору.

2. **Explain / drill-down**
   - объяснить saldo;
   - объяснить движение;
   - показать цепочку документа;
   - показать, почему запись попала туда.

3. **Cross-entity**
   - связать документ и проводки;
   - контрагента и договор;
   - номенклатуру и склад;
   - регистр и первичный документ.

4. **Period / trend**
   - изменения за месяц;
   - сравнение с предыдущим периодом;
   - необычные движения;
   - всплески активности.

5. **Anomaly / control**
   - найти аномалии;
   - найти нетипичные корреспонденции;
   - найти незакрытые хвосты;
   - найти коллизии.

6. **Heavy analytical**
   - анализ всего среза;
   - анализ всех счетов;
   - анализ компаний/контрагентов;
   - поиск отклонений от baseline.

7. **Ambiguous / fuzzy**
   - криво сформулированные вопросы;
   - вопросы с недостатком контекста;
   - вопросы, где нужна маршрутизация и уточнение.

---

## 10. Что должен вернуть benchmark

Для **каждого** вопроса Codex должен вернуть запись со следующими полями:

1. `question_id`
2. `question_text`
3. `question_class`
4. `expected_route`
5. `actual_route`
6. `sources_used`
7. `refresh_needed`
8. `latency_ms`
9. `planning_time_ms`
10. `retrieval_time_ms`
11. `response_generation_time_ms`
12. `context_size`
13. `answer_text`
14. `answer_quality_assessment`
15. `route_quality_assessment`
16. `issues_detected`
17. `recommended_fix`

---

## 11. Отчёт по итогам benchmark-run

Codex должен собрать **максимально подробный отчёт**, где будут:

### 11.1. Общая статистика
- число вопросов;
- среднее время ответа;
- медиана;
- p90;
- p95;
- средний размер контекста;
- число live-route вопросов;
- число store-route вопросов;
- число неправильных маршрутизаций;
- число деградированных ответов.

### 11.2. Анализ качества оркестрации
- где маршрутизация сработала правильно;
- где OData использован правильно;
- где MCP использован правильно;
- где snapshot/store было бы лучше;
- где система дёрнула не тот источник;
- где слишком дорого / долго.

### 11.3. Анализ онтологии и мэппинга
- где ontology помогла;
- где mapping сломал ответ;
- какие типы сущностей и связей проблемны;
- какие relation patterns надо чинить.

### 11.4. Итоговые рекомендации
- что надо чинить первым;
- что можно отложить;
- какие маршруты уже production-usable;
- какие маршруты нельзя пока давать живому пользователю.

---

## 12. Deliverables

Codex должен вернуть:

1. `slice_ingestion_report.md`
2. `ontology_mapping_audit.md`
3. `orchestration_policy_spec.md`
4. `llm_like_simulation_profile.md`
5. `benchmark_questions_35.md`
6. `benchmark_run_results.json`
7. `benchmark_run_report.md`
8. `benchmark_route_analysis.md`
9. `benchmark_final_verdict.md`

---

## 13. Критерии приёмки

Этап считается успешным, если:

1. жирный slice полноценно посажен в canonical/feature/risk store;
2. ontology + mapping прошли жёсткий аудит;
3. orchestration policy формализована;
4. Codex выполнил benchmark-run в LLM-like профиле;
5. по каждому вопросу есть route trace, timing и quality trace;
6. можно честно сказать:
   - какие маршруты уже хорошие;
   - какие требуют доработки;
   - где bottleneck;
   - где слабое место онтологии;
   - где слабое место оркестрации.

---

## 14. Резюме

Это не этап “подключили LLM и надеемся на чудо”.

Это этап:
- доведения жирного среза;
- взрослой проверки ontology/mapping;
- формализации orchestration;
- controlled benchmark-run с модель-подобным профилем;
- инженерной оценки готовности системы к реальному пользовательскому контуру.

Главная задача:
**получить честную, измеримую и трассируемую картину того, насколько система готова к следующему шагу.**