1. 이미지 라벨 + caption 생성 프롬프트

너는 Python 기반 데이터셋 라벨링 파이프라인을 구현하는 개발자다.

목표:
이미 존재하는 Dataset/{landmark_id}/catalog.json을 기준으로 MobileCLIP2-S3/S4 계열 fine-tuning용 Dataset/{landmark_id}/labels.json 생성 파이프라인을 구현한다.

중요:
이 프롬프트는 catalog.json을 새로 생성하지 않는다.
catalog.json은 별도의 catalog 생성 프롬프트로 이미 만들어져 있어야 한다.
이 작업의 최종 산출물은 labels.json이다.
catalog.json이 없거나 필수 필드가 부족하면 labels.json 생성을 중단하고 필요한 수정 사항을 보고한다.
agent가 catalog.json을 임의로 새로 만들거나 대규모 수정하지 않는다.
필요한 catalog 수정 사항은 catalog_update_suggestions 형태로 제안만 한다.

이 작업은 repository 자체만 보고 재현 가능해야 한다.
이전 대화나 외부 맥락에 의존하지 말고, 먼저 현재 repo 구조와 기존 학습 코드가 labels.json, caption_set, confusing_with, training_role, label_status를 어떻게 읽는지 확인한 뒤 구현한다.
확인한 사실과 가정은 구분해서 기록한다.
기존 코드와 충돌하는 요구사항이 있으면 구현 전에 명시한다.
구현은 작은 단위로 진행하고, 각 단계는 validation으로 확인한다.

핵심 방향:
- Vision AI가 모든 이미지마다 긴 caption_set을 직접 작성하지 않게 한다.
- Vision AI는 이미지의 scene_group, label_status, visibility, training_role 등 최소 라벨만 판단한다.
- Python 코드가 기존 catalog.json을 기준으로 caption_set, confusing_with, landmark_id, image_id를 자동 생성한다.
- 최종적으로 Dataset/{landmark_id}/에 남겨야 하는 핵심 파일은 기존 catalog.json과 새로 생성된 labels.json이다.
- scene_only_labels.json, validation_report.json은 중간/검증 산출물이며 기본적으로 debug output 또는 임시 산출물로만 저장한다.
- 최종 labels.json은 현재 학습 코드가 읽을 수 있는 JSON 배열 형태여야 한다.
- metadata wrapper는 만들지 않는다.
- caption_set에는 contrast_with와 function을 만들지 않는다.
- caption_set은 기본적으로 name_anchor 1개 + visual_feature 1개만 생성한다.
- 특수한 경우에도 caption_set은 2~3개를 넘기지 않는다.
- hard negative 정보는 training_role이 아니라 confusing_with와 Dataset/confusion_prior_v1.json으로 관리한다.
- confusion_prior는 라벨 판단과 hard negative 후보 생성을 위한 구조화 정보이며, caption text를 생성하는 재료가 아니다.

입력:
- Dataset/confusion_prior_v1.json
- Dataset/{landmark_id}/catalog.json
- Dataset/{landmark_id}/images/

출력:
- Dataset/{landmark_id}/labels.json

debug 출력:
- scene_only_labels.json
- validation_report.json
- catalog_update_suggestions.json

전역 confusion prior 입력:
프로젝트 표준 실행에서는 Dataset/confusion_prior_v1.json을 필수 입력으로 사용한다.

confusion_prior_path 규칙:
- 표준 실행에서는 confusion_prior_path가 필수이다.
- 기본 경로는 Dataset/confusion_prior_v1.json이다.
- --no-confusion-prior 플래그가 없는 상태에서 Dataset/confusion_prior_v1.json을 읽을 수 없으면 오류로 중단한다.
- 테스트/디버그 목적으로 prior 없이 실행하려면 반드시 --no-confusion-prior 플래그를 명시한다.
- --no-confusion-prior가 있으면 confusing_with는 자동 추측하지 않고 []로 둔다.
- prior가 없다는 이유로 agent나 Vision AI가 confusing candidate를 새로 추측하면 안 된다.

confusion_prior_v1.json 목적:
- 전체 랜드마크 간 헷갈릴 수 있는 관계를 미리 정의한다.
- 라벨링 주의사항, hard negative 후보, 검증 포인트로만 사용한다.
- caption_set의 text_ko/text_en에는 confusing landmark 이름이나 비교 문장을 넣지 않는다.

confusion_prior_v1.json 사용 원칙:
- confusing_landmark_ids는 agent나 Vision AI가 새로 추측해서 만들지 않는다.
- 기본값은 []이다.
- Dataset/confusion_prior_v1.json에서 현재 landmark_id와 직접 연결된 high/medium priority pair만 자동 반영한다.
- low priority pair는 기본적으로 자동 반영하지 않고 notes/warnings에만 기록한다.
- confusion_prior_v1.json에 없는 id를 confusing_landmark_ids나 confusing_with에 넣지 않는다.
- 사람이 명시적으로 override_allow_unlisted_confusions=true를 준 경우에만 prior에 없는 수동 id를 허용한다.
- 자기 자신의 landmark_id는 confusing_with에 들어가면 안 된다.
- confusion_prior의 reason_ko, labeling_note_ko, caption_rule은 caption text에 사용하지 않는다.
- 시각적으로 비슷해 보인다는 이유만으로 prior에 없는 confusing pair를 생성하지 않는다.

전체 파이프라인:

Step 0. 기존 catalog.json 검증

이 단계는 catalog.json을 생성하는 단계가 아니다.
이미 존재하는 Dataset/{landmark_id}/catalog.json을 읽고, labels.json 생성에 필요한 기준 정보가 충분한지 검증한다.

기본 입력:
- catalog_path: Dataset/{landmark_id}/catalog.json
- confusion_prior_path: Dataset/confusion_prior_v1.json
- image_dir: Dataset/{landmark_id}/images

catalog.json에는 최소한 아래 필드가 있어야 한다.

{
  "landmark_id": "",
  "landmark_name_ko": "",
  "landmark_name_en": "",
  "alias_ko": [],
  "alias_en": [],
  "visual_description_ko": "",
  "visual_description_en": "",
  "key_visual_terms_ko": [],
  "key_visual_terms_en": [],
  "confusing_landmark_ids": [],
  "allowed_scene_groups": [],
  "caption_templates": {
    "other": {
      "text_ko": "",
      "text_en": ""
    }
  },
  "scene_group_policy": {}
}

권장 추가 필드:
{
  "landmark_category": "",
  "function_description_ko": "",
  "function_description_en": "",
  "contrast_descriptions": [],
  "query_examples_ko": [],
  "query_examples_en": [],
  "visual_confidence": "high | medium | low",
  "catalog_notes": []
}

catalog.json 검증 규칙:
- landmark_id는 폴더명 또는 기존 학습 코드에서 쓰는 class id와 일치해야 한다.
- allowed_scene_groups는 비어 있으면 안 된다.
- allowed_scene_groups에는 가능한 경우 "other"를 포함한다.
- Vision AI가 선택할 scene_group은 반드시 allowed_scene_groups 안에 있어야 한다.
- caption_templates는 scene_group별 visual_feature caption 기준이다.
- caption_templates에 없는 scene_group이 있으면 catalog_update_suggestions에 기록한다.
- caption_templates["other"]가 있으면 fallback으로 사용할 수 있다.
- caption_templates 안에는 confusing landmark 이름, 별칭, 영문명, 비교 문장, 주변 위치 표현을 넣지 않는다.
- confusing_landmark_ids는 class 단위 hard negative 후보이다.
- confusing_landmark_ids는 Dataset/confusion_prior_v1.json의 high/medium direct pair와 일치해야 한다.
- catalog.json에 사람이 직접 작성한 confusing_landmark_ids가 있더라도 prior에 없는 값이면 warning 또는 validation error를 낸다.
- override_allow_unlisted_confusions=true가 없으면 prior에 없는 confusing id는 자동 제거하거나 validation error로 처리한다.
- catalog.json이 불완전하면 labels.json 생성을 중단하고 catalog_update_suggestions를 출력한다.
- agent는 catalog.json을 임의로 보강하거나 새로 작성하지 않는다.

Step 1. 이미지별 최소 라벨 생성 기능 구현

기능 이름:
classify_images_minimal

목적:
Vision AI가 각 이미지에 대해 caption 없이 최소 라벨만 생성한다.

입력:
- image_dir
- catalog_path
- confusion_prior_path
- batch_size
- output_path optional
- debug_output_dir optional
- no_confusion_prior optional

Vision AI에게 제공할 정보:
- landmark_id
- landmark_name_ko
- landmark_name_en
- alias_ko
- alias_en
- visual_description_ko/en
- key_visual_terms_ko/en
- allowed_scene_groups
- catalog.confusing_landmark_ids
- related_confusion_prior
  - 현재 landmark_id와 관련된 confusion_prior_v1.json 항목만 포함
  - 라벨 판단 주의사항으로만 사용
  - caption 생성에는 사용하지 않음
- 이미지 파일명과 이미지

Vision AI 출력 스키마:
[
  {
    "file_name": "",
    "scene_group": "",
    "label_status": "confirmed | uncertain | rejected",
    "scope_status": "in_scope | similar_out_of_scope | out_of_scope_other | screen_or_document",
    "landmark_visibility": "dominant | clear_partial | small_background | background_only | not_visible",
    "multi_landmark_present": false,
    "background_landmark_ids": [],
    "view_type": "front_exterior | side_exterior | wide_view | detail | interior | signage",
    "time_condition": "day | night | dusk | indoor_lighting",
    "distance_scale": "close | medium | far | aerial_or_panorama",
    "quality_status": ["ok"],
    "training_role": "train_positive | low_weight_positive | calibration_only | eval_only | exclude",
    "hard_case_tags": [],
    "source_group_id": "",
    "schema_notes": [],
    "uncertain_reason": ""
  }
]

중요:
- Vision AI는 caption_set을 작성하지 않는다.
- Vision AI는 function, contrast_with, name_anchor, visual_feature caption을 작성하지 않는다.
- Vision AI는 scene_group을 반드시 catalog.allowed_scene_groups 안에서 선택한다.
- allowed_scene_groups에 맞는 것이 없으면 "other"를 사용한다.
- Vision AI는 related_confusion_prior를 보고 헷갈릴 수 있는 이미지를 더 조심해서 판단한다.
- 하지만 Vision AI는 confusing landmark 이름을 caption_set에 넣지 않는다.
- 현재 이미지에 배경으로 다른 랜드마크가 보이면 background_landmark_ids에만 기록한다.
- 확실하지 않으면 label_status를 uncertain으로 두고 uncertain_reason에 이유를 쓴다.
- label_status가 rejected이면 caption_set은 나중에 Python에서 []로 처리한다.
- rejected인데 hard negative 또는 calibration에 쓸 수 있으면 training_role은 calibration_only로 둔다.
- training_role에 hard_negative라는 값은 절대 쓰지 않는다.
- source_group_id는 동일 출처, 동일 촬영 묶음, 중복 이미지 그룹이 명확하게 제공된 경우에만 채운다.
- 파일명 패턴이 비슷하다는 이유만으로 source_group_id를 만들지 않는다.
- source_group_id가 확실하지 않으면 빈 문자열로 둔다.

Step 2. Python 후처리 기능 구현

기능 이름:
build_final_labels

목적:
Vision AI의 최소 라벨 결과와 기존 catalog.json, Dataset/confusion_prior_v1.json을 결합해 최종 labels.json을 만든다.

입력:
- scene_only_labels data or path
- catalog.json
- image_dir
- output_path: Dataset/{landmark_id}/labels.json
- confusion_prior_path: Dataset/confusion_prior_v1.json
- debug_output_dir optional
- no_confusion_prior optional

Python이 자동으로 채울 필드:
- image_id:
  - 기본은 file_name에서 확장자 제거
  - 단, 전체 Dataset 기준 중복 가능성이 있으면 landmark_id + "_" + file stem 사용
- file_name:
  - Dataset/{landmark_id}/ 기준 상대 경로로 저장한다.
  - 권장 형식은 "images/00001.jpg"이다.
  - 검증기는 "images/00001.jpg"와 "00001.jpg"를 모두 읽을 수 있게 하되, 최종 labels.json에는 "images/파일명" 형식을 권장한다.
- landmark_id:
  - catalog.landmark_id를 사용한다.
- confusing_with:
  - Dataset/confusion_prior_v1.json에서 현재 landmark_id와 직접 연결된 high/medium pair
  - plus catalog.confusing_landmark_ids 중 prior에 존재하거나 명시적으로 override된 id
  - 둘을 union하고 중복 제거
  - 자기 자신은 제거
  - --no-confusion-prior이면 자동 추측하지 않고 []로 둔다.
- caption_set:
  - rejected 또는 training_role이 exclude이면 []
  - 그 외에는 name_anchor 1개 + visual_feature 1개
- caption target:
  - 항상 catalog.landmark_id
- caption_type:
  - name_anchor, visual_feature만 기본 사용

caption_set 생성 규칙:

1. name_anchor:
name_anchor caption은 일반 단어만 쓰면 안 된다.

나쁜 예:
{
  "caption_type": "name_anchor",
  "target": "myeongdong_cathedral",
  "text_ko": "사진",
  "text_en": "photo"
}

좋은 예:
{
  "caption_type": "name_anchor",
  "target": "myeongdong_cathedral",
  "text_ko": "명동성당 사진",
  "text_en": "Myeongdong Cathedral photo"
}

규칙:
- text_ko = "{landmark_name_ko} 사진"
- text_en = "{landmark_name_en} photo"

2. visual_feature:
scene_group을 보고 catalog.caption_templates[scene_group]에서 가져온다.

{
  "caption_type": "visual_feature",
  "target": "",
  "text_ko": "",
  "text_en": ""
}

3. scene_group template이 없으면:
- caption_templates["other"]가 있으면 사용한다.
- 없으면 catalog.visual_description_ko/en을 짧은 fallback caption으로 사용한다.
- fallback도 없으면 name_anchor만 사용한다.
- 이 경우 catalog_update_suggestions 또는 validation warning에 기록한다.
- agent가 catalog.json을 즉시 수정하지 않는다.

4. caption_set에는 function을 넣지 않는다.
5. caption_set에는 contrast_with를 넣지 않는다.
6. caption text에는 confusing landmark 이름을 넣지 않는다.
7. confusion_prior_v1.json의 reason_ko, labeling_note_ko, caption_rule은 caption text에 사용하지 않는다.
8. confusing landmark 이름, alias, 영문명은 caption text에 넣지 않는다.

Step 3. 검증 기능 구현

기능 이름:
validate_labels

검증 규칙:
- 최종 labels.json 최상위는 반드시 JSON 배열이어야 한다.
- metadata wrapper를 만들지 않는다.
- image_id는 비어 있으면 안 된다.
- image_id 중복이 없어야 한다.
- file_name에 해당하는 실제 이미지 파일이 image_dir에 존재해야 한다.
- file_name은 최종 labels.json에서 가능한 한 "images/파일명" 형식을 사용한다.
- landmark_id는 catalog.landmark_id와 같아야 한다.
- label_status는 confirmed, uncertain, rejected 중 하나여야 한다.
- scope_status는 in_scope, similar_out_of_scope, out_of_scope_other, screen_or_document 중 하나여야 한다.
- landmark_visibility는 dominant, clear_partial, small_background, background_only, not_visible 중 하나여야 한다.
- landmark_visibility에 weak를 쓰면 안 된다.
- view_type은 front_exterior, side_exterior, wide_view, detail, interior, signage 중 하나여야 한다.
- time_condition은 day, night, dusk, indoor_lighting 중 하나여야 한다.
- distance_scale은 close, medium, far, aerial_or_panorama 중 하나여야 한다.
- quality_status는 배열이어야 한다.
- quality_status 허용값은 ok, blurry, dark, low_resolution, occluded, cropped_too_much이다.
- quality_status에서 ok는 단독으로만 사용해야 한다.
- watermark, backlit, reflection은 quality_status가 아니라 hard_case_tags에 있어야 한다.
- training_role은 train_positive, low_weight_positive, calibration_only, eval_only, exclude 중 하나여야 한다.
- training_role에 hard_negative를 쓰면 안 된다.
- scene_group은 catalog.allowed_scene_groups 안에 있어야 한다.
- allowed_scene_groups에 없는 scene_group이면 오류로 처리한다.
- caption_set 안의 caption_type은 name_anchor 또는 visual_feature만 허용한다.
- caption_set 안에 function이 있으면 오류이다.
- caption_set 안에 contrast_with가 있으면 오류이다.
- caption target은 빈 문자열이면 안 된다.
- confirmed/uncertain의 caption target은 landmark_id와 같아야 한다.
- rejected 또는 exclude의 caption_set은 반드시 []이어야 한다.
- name_anchor caption의 text_ko가 "사진"만 있거나 text_en이 "photo"만 있으면 오류로 처리한다.
- name_anchor caption은 landmark_name_ko 또는 landmark_name_en을 포함해야 한다.
- caption text에 confusing_landmark_ids의 이름, 별칭, 영문명이 들어가면 경고 또는 오류로 처리한다.
- caption text에 주소성 표현, 주변 landmark 기반 표현, "~옆", "~근처", "located near", "next to" 등이 들어가면 경고한다.
- confusion_prior_path가 제공되면 파일은 JSON 배열이어야 한다.
- confusion_prior_v1.json의 각 항목은 landmark_a, landmark_b, priority를 가져야 한다.
- priority는 high, medium, low 중 하나여야 한다.
- landmark_a와 landmark_b는 같으면 안 된다.
- confusion_prior에서 가져온 confusing_with id는 자기 자신이면 안 된다.
- low priority pair가 자동으로 confusing_with에 들어가면 warning 또는 error를 낸다.
- prior에 없는 id가 confusing_with에 들어가면 override_allow_unlisted_confusions=true가 없는 한 validation error를 낸다.
- caption text에 confusion_prior에 등장하는 상대 landmark 이름/alias가 들어가면 warning 또는 오류로 처리한다.
- source_group_id는 확실한 출처/중복/촬영 묶음 근거가 없으면 빈 문자열이어야 한다.
- 파일명 패턴만으로 만들어진 source_group_id가 의심되면 warning을 낸다.

검증 결과:
- validate_labels는 validation report 객체를 반환한다.
- 기본 실행에서는 Dataset/{landmark_id}/에 validation_report.json을 남기지 않는다.
- 사용자가 --keep-intermediate 또는 --debug-output-dir을 지정하면 validation_report.json을 저장한다.
- 검증 실패 시에는 validation_report.json을 저장하거나 콘솔에 오류 요약을 출력해 원인 파악이 가능해야 한다.

validation_report.json 형식:
{
  "total_count": 0,
  "valid_count": 0,
  "error_count": 0,
  "warning_count": 0,
  "errors": [
    {
      "file_name": "",
      "field": "",
      "message": ""
    }
  ],
  "warnings": [
    {
      "file_name": "",
      "field": "",
      "message": ""
    }
  ],
  "stats": {
    "scene_group_counts": {},
    "training_role_counts": {},
    "label_status_counts": {},
    "quality_status_counts": {},
    "confusing_with_counts": {},
    "confusion_prior_injected_counts": {}
  }
}

Step 4. CLI 구현

파일:
scripts/generate_labels.py

CLI 명령 예시:

1. 이미지 최소 라벨 생성:
python scripts/generate_labels.py classify-images \
  --image-dir Dataset/mmca_seoul/images \
  --catalog-path Dataset/mmca_seoul/catalog.json \
  --batch-size 20 \
  --confusion-prior-path Dataset/confusion_prior_v1.json \
  --debug-output-dir outputs/labeling_runs/mmca_seoul_debug

2. 최종 labels.json 생성:
python scripts/generate_labels.py build-labels \
  --image-dir Dataset/mmca_seoul/images \
  --catalog-path Dataset/mmca_seoul/catalog.json \
  --scene-labels-path outputs/labeling_runs/mmca_seoul_debug/scene_only_labels.json \
  --confusion-prior-path Dataset/confusion_prior_v1.json \
  --output-path Dataset/mmca_seoul/labels.json

3. 검증:
python scripts/generate_labels.py validate \
  --image-dir Dataset/mmca_seoul/images \
  --catalog-path Dataset/mmca_seoul/catalog.json \
  --labels-path Dataset/mmca_seoul/labels.json \
  --confusion-prior-path Dataset/confusion_prior_v1.json \
  --debug-output-dir outputs/labeling_runs/mmca_seoul_debug

4. 전체 실행:
python scripts/generate_labels.py run-all \
  --image-dir Dataset/mmca_seoul/images \
  --catalog-path Dataset/mmca_seoul/catalog.json \
  --batch-size 20 \
  --confusion-prior-path Dataset/confusion_prior_v1.json \
  --output-path Dataset/mmca_seoul/labels.json \
  --debug-output-dir outputs/labeling_runs/mmca_seoul_debug

5. prior 없이 테스트 실행:
python scripts/generate_labels.py validate \
  --image-dir Dataset/mmca_seoul/images \
  --catalog-path Dataset/mmca_seoul/catalog.json \
  --labels-path Dataset/mmca_seoul/labels.json \
  --no-confusion-prior

prior 없이 실행할 때:
- --no-confusion-prior를 명시해야 한다.
- confusing_with는 []로 둔다.
- agent나 Vision AI가 헷갈릴 후보를 새로 추측하지 않는다.

중간 산출물 저장 규칙:
- 기본 실행의 최종 목적지는 Dataset/{landmark_id}/labels.json이다.
- Dataset/{landmark_id}/catalog.json은 입력 파일이며 새로 생성하지 않는다.
- scene_only_labels.json, validation_report.json, catalog_update_suggestions.json은 Dataset/{landmark_id}/에 기본 저장하지 않는다.
- 중간 산출물이 필요하면 --keep-intermediate 또는 --debug-output-dir을 사용한다.
- debug output은 outputs/labeling_runs/{landmark_id}_debug/ 아래에 저장하는 것을 권장한다.

Step 5. Vision AI 호출부는 교체 가능하게 구현

Vision AI provider를 추상화한다.

구조:
src/landmark_labeling/vision_labeler.py

인터페이스:
class VisionLabeler:
    def classify_images(self, images, catalog, related_confusion_prior=None) -> list[dict]:
        pass

구현체:
- DummyVisionLabeler: 테스트용. 이미지 파일명 기반으로 임시 출력.
- OpenAIVisionLabeler 또는 ExternalVisionLabeler: 실제 Vision API 호출용.
- ManualJsonLabeler: 이미 사람이 만든 최소 라벨 JSON을 읽는 모드.

주의:
- API key가 없을 때도 dry-run과 validation은 작동해야 한다.
- 실제 Vision API 호출 코드는 환경변수에서 API key를 읽도록 한다.
- Vision API 결과는 반드시 JSON 파싱 후 validate_minimal_labels를 통과해야 한다.
- Vision AI prompt에는 caption_set을 생성하지 말라고 명시한다.
- Vision AI prompt에는 confusion prior가 caption 생성 재료가 아니라 라벨 판단 주의사항이라고 명시한다.

Step 6. 모듈 구조

구현 파일:
- scripts/generate_labels.py
- src/landmark_labeling/catalog.py
- src/landmark_labeling/confusion_prior.py
- src/landmark_labeling/vision_labeler.py
- src/landmark_labeling/prompts.py
- src/landmark_labeling/postprocess.py
- src/landmark_labeling/validate_labels.py
- src/landmark_labeling/io_utils.py

각 파일 역할:

catalog.py:
- load_catalog
- validate_catalog
- validate_catalog_for_labeling
- get_name_anchor
- get_caption_template
- collect_catalog_update_suggestions

confusion_prior.py:
- load_confusion_prior
- validate_confusion_prior
- get_related_confusions
- get_confusing_ids_for_landmark
- merge_confusing_ids

vision_labeler.py:
- VisionLabeler interface
- DummyVisionLabeler
- ManualJsonLabeler
- 실제 Vision provider adapter

prompts.py:
- minimal image classification prompt 생성
- related_confusion_prior를 라벨 판단 주의사항으로만 전달
- Vision AI에게 caption_set을 생성하지 말라고 명시
- Vision AI에게 confusing landmark 이름을 caption에 넣지 말라고 명시

postprocess.py:
- build_caption_set
- normalize_item
- build_final_labels
- inject_confusing_with
- fill_image_id
- enforce_training_role_by_scene_group
- apply_confusion_prior

validate_labels.py:
- validate_item
- validate_labels
- validate_confusion_prior
- make_validation_report

io_utils.py:
- list_images
- read_json
- write_json
- ensure_json_array

Step 7. scene_group별 training_role 보정 규칙

catalog.json에 scene_group_policy가 있으면 사용한다.
없으면 기본 규칙만 사용한다.

예:
{
  "scene_group_policy": {
    "generic_interior": {
      "max_training_role": "low_weight_positive"
    },
    "artwork_interior": {
      "max_training_role": "low_weight_positive"
    },
    "screen_or_document": {
      "force_training_role": "exclude"
    }
  }
}

보정 규칙:
- scene_group이 generic_interior이고 AI가 train_positive로 줬으면 low_weight_positive로 낮춘다.
- scene_group이 artwork_interior이고 landmark 고유성이 약하면 low_weight_positive로 낮춘다.
- label_status가 rejected이면 training_role은 calibration_only 또는 exclude만 허용한다.
- training_role 보정이 발생하면 schema_notes에 이유를 추가한다.
- low_weight_positive는 기본적으로 라벨 태그이다. 실제 loss weight를 낮추는 것은 학습 코드가 지원할 때만 가능하다. 학습 코드가 지원하지 않으면 문서에 명시한다.

Step 8. 산출물

필수 입력:
- Dataset/{landmark_id}/catalog.json
- Dataset/{landmark_id}/images/
- Dataset/confusion_prior_v1.json

필수 최종 산출물:
- Dataset/{landmark_id}/labels.json

중간/검증 산출물:
- scene_only_labels.json
- validation_report.json
- catalog_update_suggestions.json

중간/검증 산출물 저장 규칙:
- 기본 실행에서는 Dataset/{landmark_id}/에 labels.json만 새로 생성하거나 갱신한다.
- catalog.json은 입력 파일이므로 새로 생성하지 않는다.
- scene_only_labels.json, validation_report.json, catalog_update_suggestions.json은 기본적으로 임시 값 또는 debug output으로만 저장한다.
- 사용자가 --keep-intermediate 또는 --debug-output-dir 옵션을 주면 중간 산출물을 저장한다.
- validation 실패 시에는 validation_report.json을 저장하거나 오류 요약을 출력한다.

labels.json은 반드시 아래 구조여야 한다.

[
  {
    "image_id": "",
    "file_name": "",
    "landmark_id": "",
    "label_status": "",
    "scope_status": "",
    "landmark_visibility": "",
    "multi_landmark_present": false,
    "background_landmark_ids": [],
    "confusing_with": [],
    "scene_group": "",
    "view_type": "",
    "time_condition": "",
    "distance_scale": "",
    "quality_status": [],
    "training_role": "",
    "hard_case_tags": [],
    "source_group_id": "",
    "caption_set": [],
    "schema_notes": [],
    "uncertain_reason": ""
  }
]

절대 만들지 말아야 하는 것:
- { "metadata": ..., "labels": [...] } 형태의 labels.json
- catalog.json을 새로 생성하는 것
- catalog.json을 agent가 임의로 대규모 수정하는 것
- caption_type: "contrast_with"
- caption_type: "function"
- caption target: ""
- training_role: "hard_negative"
- landmark_visibility: "weak"
- scope_status: "out_of_scope"
- quality_status: ["ok", "blurry"]처럼 ok와 다른 값이 섞인 배열
- confusion prior의 상대 landmark 이름을 caption text에 넣는 것
- Dataset/{landmark_id}/에 중간 산출물을 기본으로 계속 쌓아두는 것
- prior에 없는 confusing_landmark_ids를 agent가 임의로 추측해서 추가하는 것
- name_anchor caption을 "사진" 또는 "photo"처럼 일반어만으로 생성하는 것
- 파일명 패턴만 보고 source_group_id를 자동 생성하는 것

개발 완료 기준:
1. 현재 repo 구조와 기존 학습 코드의 labels.json 읽기 방식을 확인하고 기록한다.
2. 기존 catalog.json을 읽고 labels 생성에 필요한 필드를 검증한다.
3. catalog.json이 없거나 필수 필드가 부족하면 labels.json 생성을 중단하고 catalog_update_suggestions를 출력한다.
4. sample catalog와 sample minimal labels로 labels.json을 생성할 수 있다.
5. 최종 labels.json은 validator를 통과한다.
6. rejected/exclude 이미지의 caption_set은 []이다.
7. confirmed 이미지의 caption_set은 name_anchor + visual_feature를 가진다.
8. name_anchor는 "{landmark_name_ko} 사진" / "{landmark_name_en} photo" 형식이다.
9. 모든 caption target은 landmark_id와 같다.
10. scene_group별 caption template이 적용된다.
11. scene_group은 catalog.allowed_scene_groups 안에 있어야 한다.
12. confusing_with는 Dataset/confusion_prior_v1.json의 high/medium direct pair에서 자동 주입된다.
13. low priority pair는 기본적으로 confusing_with에 자동 반영되지 않는다.
14. prior에 없는 confusing id는 override_allow_unlisted_confusions=true가 없는 한 자동 반영되지 않는다.
15. confusion prior의 reason_ko나 상대 landmark 이름이 caption text에 섞이지 않는다.
16. file_name은 최종 labels.json에서 "images/파일명" 형식을 권장한다.
17. source_group_id는 근거가 없으면 빈 문자열이다.
18. validation report에는 scene_group/training_role/label_status/quality_status/confusing_with 통계가 나온다.
19. validation report에는 confusion_prior 기반으로 주입된 confusing_with 통계가 기록된다.
20. 기존 학습 코드가 새 labels.json을 실제로 읽을 수 있는지 최소 smoke test를 수행한다.
21. API key가 없어도 DummyVisionLabeler 또는 ManualJsonLabeler로 run-all/validate가 동작한다.
22. 기본 실행 후 Dataset/{landmark_id}/에는 기존 catalog.json과 생성된 labels.json 중심으로 정리되어 있어야 한다.
23. 구현 완료 후 무엇을 왜 구현했는지, 어떻게 실행하는지, 어떤 검증을 통과했는지 문서화한다.