README.md

Camera Analysis Pipeline

Этот набор документов описывает roadmap и PR pipeline для нового функционала Анализ картинки с семантическими подсказками.

Цель:

• превратить текущий camera coach из набора эвристических подсказок в explainable AI-систему;
• сохранить mobile-first архитектуру;
• показать технологическую сложность, достаточную для диплома и диссертации;
• разложить работу на детерминированные PR, которые можно безопасно отдавать разным AI-агентам.

Как читать

Если хочется общего понимания, начинайте с:

• 30-semantic-camera-source-of-truth.md
• 31-dataset-eval-implementation-plan.md
• 32-semantic-eval-output-contract.md
• 33-semantic-current-baseline-findings.md
• 00-overview.md
• 01-roadmap.md
• 03-domain-contracts.md
• 04-explainability-contract.md
• camera-analysis-requirements-draft.md
• camera-analysis-v1-architecture.md
• 02-pipeline-architecture.md

Если хочется отдавать работу агентам по частям:

• roadmap по фазам: 01-roadmap.md
• implementation backlog и детерминированные PR: 11-implementation-backlog.md
• готовые промпты для агентов: 12-agent-prompts.md
• шаблон briefing-а: 13-agent-briefing-template.md

Если хочется перейти к следующему этапу hybrid deterministic + neural:

• архитектурное направление встроено в 02-pipeline-architecture.md
• roadmap расширен в 01-roadmap.md
• backlog, PR и подробный DoD добавлены в 11-implementation-backlog.md
• research framing и границы hybrid stage зафиксированы в 14-hybrid-research-framing.md
• evidence taxonomy для PR-H02 зафиксирована в 15-evidence-taxonomy-contract.md
• dataset schema и labeling protocol для PR-H03 зафиксированы в 16-dataset-schema-and-labeling-guide.md
• AVA usage policy и pretraining boundaries для PR-H04 зафиксированы в 17-ava-usage-policy-and-pretraining-design.md
• model architecture spec для PR-H05 зафиксирован в 18-hybrid-model-architecture-spec.md
• runtime/domain contract для PR-H06 зафиксирован в 19-neural-evidence-domain-contract.md
• runtime wrapper и cadence policy для PR-H07 зафиксированы в 20-on-device-inference-wrapper.md
• fusion weighting и calibration policy для PR-H09 зафиксированы в 21-hybrid-fusion-layer.md
• gated offloading contract для PR-H12 зафиксирован в 22-offloading-contract.md
• hybrid eval harness для PR-H14 зафиксирован в 23-hybrid-eval-harness.md
• agent prompts для hybrid stage добавлены в 12-agent-prompts.md

Если хочется перейти к этапу semantic screen tips:

• canonical product/research source-of-truth для следующего этапа зафиксирован в 30-semantic-camera-source-of-truth.md
• dataset/eval execution plan для следующего этапа зафиксирован в 31-dataset-eval-implementation-plan.md
• semantic eval output contract для dataset/baseline проверки зафиксирован в 32-semantic-eval-output-contract.md
• current real-runtime baseline findings и следующий ranked PR backlog зафиксированы в 33-semantic-current-baseline-findings.md
• closed catalog semantic tips для PR-S01 зафиксирован в 24-semantic-tip-taxonomy-and-action-catalog.md
• VLM visual semantic evidence contract для PR-S02 зафиксирован в 25-vlm-visual-semantic-evidence-contract.md
• pause VLM evidence provider prototype для PR-S03 зафиксирован в 27-pause-vlm-evidence-provider-prototype.md
• semantic fusion and tip planner для PR-S04 зафиксирован в 26-semantic-tip-fusion-and-planner.md
• VLM-labeled semantic tip dataset loop для PR-S06 зафиксирован в 28-vlm-labeled-semantic-tip-dataset.md
• on-device semantic evidence distillation plan для PR-S07 зафиксирован в 29-on-device-semantic-evidence-distillation-plan.md
• prompts для semantic stage добавлены в 12-agent-prompts.md

Главная идея

Для camera analysis v1 нельзя делать ставку только на:

• набор коротких эвристик;
• или один черный ящик, который "смотрит на кадр" и сразу пишет текст.

Нужен каскадный pipeline, где:

• fast low-level сигналы работают локально и часто;
• semantic critique строится поверх структурированных признаков;
• explanation всегда восстанавливается до цепочки observation -> interpretation -> recommendation;
• текущий app UI может показывать эту цепочку через sheet Почему?: verdict/confidence, evidence, semantic action ids, pipeline signals, fallback/assumptions и trace ids;
• тяжелый reasoning включается в первую очередь в pause;
• live остается быстрым, стабильным и пригодным для мобильного устройства.

Основные принципы

• offline-first: базовый путь должен работать локально.
• cascade-by-cost: самые дорогие вычисления должны запускаться реже.
• explainability-by-construction: любой совет должен быть обоснован внутренним trace.
• scene-aware: критика зависит от типа cinematic-сцены.
• deterministic PR units: каждый PR должен иметь узкие границы и проверяемый DoD.

Ключевые артефакты пакета

• 00-overview.md: зачем вообще нужен новый pipeline
• 01-roadmap.md: фазы проекта
• 02-pipeline-architecture.md: сжатая схема модулей и потоков
• 03-domain-contracts.md: source-of-truth контракты PR-002
• 04-explainability-contract.md: source-of-truth traceability contract PR-003
• 05-feature-snapshot-aggregator.md: source-of-truth дизайн Feature Snapshot Aggregator PR-004
• 06-scene-semantics-layer.md: source-of-truth дизайн Scene Semantics Layer (PrimarySubjectResolver + SceneTypeClassifier) PR-005/PR-006
• 07-critique-engine.md: source-of-truth дизайн FrameCritiqueEngine PR-007
• 08-ui-integration.md: source-of-truth дизайн UI интеграции (Live Hint Adapter, Pause Critique Card, Overlay Annotations) PR-009/PR-010/PR-011
• 09-reasoning-provider.md: source-of-truth дизайн ReasoningProvider и pause-only LLM слоя PR-012/PR-013
• 10-eval-harness.md: source-of-truth дизайн eval harness PR-014
• 14-hybrid-research-framing.md: source-of-truth research framing для PR-H01
• 15-evidence-taxonomy-contract.md: source-of-truth evidence taxonomy для PR-H02
• 16-dataset-schema-and-labeling-guide.md: source-of-truth dataset schema и labeling guide для PR-H03
• 17-ava-usage-policy-and-pretraining-design.md: source-of-truth AVA usage policy и pretraining design для PR-H04
• 18-hybrid-model-architecture-spec.md: source-of-truth compact neural evidence model spec для PR-H05
• 19-neural-evidence-domain-contract.md: source-of-truth runtime/domain contract для PR-H06
• 20-on-device-inference-wrapper.md: source-of-truth on-device inference wrapper и cadence policy для PR-H07
• 21-hybrid-fusion-layer.md: source-of-truth bounded fusion, weighting and calibration policy для PR-H09
• 22-offloading-contract.md: source-of-truth gated offloading contract для PR-H12
• 23-hybrid-eval-harness.md: source-of-truth hybrid eval harness, ablation compare и mobile/explainability gates для PR-H14
• 24-semantic-tip-taxonomy-and-action-catalog.md: source-of-truth semantic tip taxonomy, action catalog и screen-tip copy contract для PR-S01
• 25-vlm-visual-semantic-evidence-contract.md: source-of-truth VLM visual semantic evidence request/response contract для PR-S02
• 27-pause-vlm-evidence-provider-prototype.md: source-of-truth pause-only prototype wiring, fallback/timeout policy и integration test matrix для PR-S03
• 26-semantic-tip-fusion-and-planner.md: source-of-truth semantic tip planner, bounded VLM rerank policy и live/pause tip selection contract для PR-S04
• 28-vlm-labeled-semantic-tip-dataset.md: source-of-truth teacher-reviewed semantic tip dataset schema, hard-case exchange и starter fixtures для PR-S06
• 29-on-device-semantic-evidence-distillation-plan.md: source-of-truth distillation plan от VLM teacher к компактной on-device semantic evidence model для PR-S07
• 30-semantic-camera-source-of-truth.md: canonical product/research source-of-truth для следующего этапа semantic camera analysis
• 31-dataset-eval-implementation-plan.md: implementation-ready plan для dataset freeze, semantic eval, good-frame preservation gates и technical quality gates
• 32-semantic-eval-output-contract.md: JSONL-контракт candidate outputs для проверки подсказок на dataset/eval
• 33-semantic-current-baseline-findings.md: current real-runtime baseline, gaps and next ranked implementation PRs
• camera-analysis-requirements-draft.md: требования и продуктовые решения
• camera-analysis-v1-architecture.md: подробная архитектура
• 11-implementation-backlog.md: tracks и PR-пайплайн
• 12-agent-prompts.md: промпты для AI-агентов

Практическая рекомендация

Если цель сейчас перейти к реализации без хаоса, оптимальный порядок такой:

1. Зафиксировать contracts и доменную модель.
2. Собрать deterministic critique core без LLM.
3. Подключить pause expanded analysis.
4. Перевести live на новую модель hint-ов.
5. Добавить LLM только как controlled reasoning/text layer.
6. После этого строить eval и runtime feedback loop.