Dev

.context/architecture.md

@@ -0,0 +1,45 @@
+# Discoverex Architecture & Module Organization
+
+이 문서는 Discoverex 프로젝트의 아키텍처 설계와 모듈 구성의 기준을 정의합니다.
+
+## 1. 헥사고널 아키텍처 (Hexagonal Layout)
+
+이 프로젝트는 헥사고널 아키텍처를 따르며, 도메인 로직과 외부 어댑터를 명확히 분리합니다.
+
+- `src/discoverex/domain`: 캐논 DTO, 불변식, 도메인 서비스 (SSOT)
+- `src/discoverex/application/ports`: 모델/스토리지/트래킹/IO/리포팅 인터페이스
+- `src/discoverex/application/use_cases`: 파이프라인 오케스트레이션 로직 (`generate`, `verify`, `animate`)
+- `src/discoverex/adapters/inbound/cli`: Typer CLI 진입점 (`discoverex`)
+- `src/discoverex/adapters/outbound`: 외부 연동 구현체 (HF 모델, MinIO, MLflow 등)
+- `src/discoverex/bootstrap`: Hydra 설정을 기반으로 애플리케이션 컨텍스트 조립 (Composition Root)
+
+## 2. 핵심 원칙
+
+- **Scene 중심**: Scene이 시스템의 루트 엔티티이며 모든 파이프라인의 기준입니다.
+- **포트 의존성**: 유스케이스는 포트 인터페이스에만 의존하며, 구체적인 어댑터 구현을 직접 참조하지 않습니다.
+- **설정 기반 조립**: Hydra 설정을 통해 실행 시점에 어댑터를 동적으로 교체합니다.
+- **불변성 유지**: 도메인 객체는 불변식을 유지하며, 어댑터는 캐논 세만틱을 변경할 수 없습니다.
+
+## 3. 모듈 및 레이어링 가이드
+
+- **파일당 단일 책임**: 각 파일은 하나의 책임만 가지며, 200라인 이하 유지를 권장합니다.
+- **캡슐화**: `__init__.py`를 적극 활용하여 패키지 내부를 캡슐화하고 안정적인 임포트 경로를 제공합니다.
+- **어댑터 분리**: 외부 라이브러리(Transformers, PyTorch 등) 의존성은 반드시 `adapters/outbound` 내부의 특정 어댑터에만 국한시킵니다.
+
+## 4. 제거된 레거시 레이어 (Hard-cut)
+
+아래 레이어들은 더 이상 사용되지 않으며, 새로운 구조로 대체되었습니다.
+- `src/discoverex/pipelines`
+- `src/discoverex/cli` -> `adapters/inbound/cli`로 이동
+- `src/discoverex/generation`
+- `src/discoverex/verification`
+- `src/discoverex/ux`
+- `src/discoverex/storage`
+- `src/discoverex/tracking`
+
+## 5. 설정 구조 (Hydra)
+
+`conf/` 디렉토리는 어댑터와 모델의 조립 방식을 정의합니다.
+- `conf/models/`: 모델 어댑터 설정 (hidden_region, inpaint, perception, fx)
+- `conf/adapters/`: 인프라 어댑터 설정 (artifact_store, metadata_store, tracker)
+- `conf/*.yaml`: 실행 파이프라인별 기본 설정 조합

.context/canon.md

@@ -0,0 +1,310 @@
+# Discoverex Scene Canonical Spec v1 (엄밀 정의)
+
+> 목적
+
+* 생성/검증/UX/학습 준비 전 파이프라인이 공통으로 사용하는 **단일 Scene 표현**
+* 파이프라인 조합이 늘어나도 흔들리지 않는 **전역 계약(Contract)**
+* 현재 버전은 **Region-first + bbox-only**
+
+## 실행 책임 경계
+
+* 엔진은 flow 정의, CLI, execution contract, execution context preparation을 소유한다.
+* Prefect가 직접 모니터링하는 대상은 엔진의 `run-engine-job` flow다.
+* deployment 등록, worker/work pool/queue 운영, scheduling, 외부 job submission은 운영 계층 책임이다.
+
+---
+
+## 1) 용어
+
+* Scene: 배경 + 배치된 구성 + 목표/정답 + 검증 결과를 포함한 퍼즐 아이템 1개
+* Region: Scene 좌표계 상의 2D 영역. 현재는 bbox만 사용
+* AssetRef: 파일/오브젝트스토리지/URL 등 외부 저장소의 참조 문자열
+* Signals: 스코어 산출에 사용된 요약 신호(수치/카운트/간단 통계). 상세 정책은 비포함
+
+---
+
+## 2) 전역 불변 조건(Invariants)
+
+* Scene은 항상 `scene_id`와 `version_id`를 가진다
+* 좌표는 **background 이미지의 절대 픽셀 좌표계** 기준이다
+* Region geometry는 현재 **bbox-only**
+* Answer는 **Region 기반**이다: `answer.answer_region_ids`가 정답의 유일한 판정 기준이다
+* Verification은 score 중심이며, `final.pass`는 `logical.pass`와 `perception.pass`에 의해 결정된다(결정 정책 자체는 외부 정책)
+* `meta.model_versions`는 실행에 사용된 모델/컴포넌트 버전을 기록한다
+
+---
+
+## 3) 데이터 타입
+
+* `ID`: 문자열. 충돌 방지 목적(예: ULID/UUID). 구체 포맷은 미정
+* `Timestamp`: ISO 8601 문자열
+* `Score`: 실수(float). 범위는 정책에 의해 정의
+* `PassFlag`: boolean
+* `JsonDict`: JSON object
+* `StringMap`: `{ string: string }`
+
+---
+
+## 4) 최상위 구조
+
+### 4.1 Scene
+
+필수 필드:
+
+* `meta: Meta`
+* `background: Background`
+* `regions: Region[]` (빈 배열 허용. 단, answer가 존재하면 해당 region_id는 존재해야 함)
+* `composite: Composite` (최소 final_image_ref 필요)
+* `goal: Goal` (구조만. 정책 상세 미정)
+* `answer: Answer`
+* `verification: VerificationBundle`
+* `difficulty: Difficulty`
+
+선택 필드:
+
+* `objects: ObjectGroup[]` (의미/관계용 grouping. 판정 기준 아님)
+
+---
+
+## 5) Meta
+
+### 5.1 Meta
+
+필수:
+
+* `scene_id: ID`
+* `version_id: ID`
+* `status: "candidate" | "approved" | "failed"`
+* `pipeline_run_id: ID` (해당 Scene version을 생성/갱신한 실행 단위)
+* `config_version: string` (생성/검증 정책 묶음 버전. 예: "v1")
+* `model_versions: StringMap` (키 예: "hidden_region", "inpaint", "perception", "fx")
+* `created_at: Timestamp`
+* `updated_at: Timestamp`
+
+권장(옵션):
+
+* `parent_version_id?: ID` (편집/재생성 등으로 파생된 경우)
+* `tags?: string[]` (목표 유형 등 검색용)
+* `notes?: string` (사람 메모)
+
+불변:
+
+* `scene_id`는 동일 퍼즐 아이템 계열에서 고정, `version_id`는 변경마다 새로 발급
+
+---
+
+## 6) Background
+
+### 6.1 Background
+
+필수:
+
+* `asset_ref: AssetRef`
+* `width: int` (px)
+* `height: int` (px)
+
+권장(옵션):
+
+* `metadata?: JsonDict` (촬영/출처/라이선스/해상도 등)
+
+---
+
+## 7) Region
+
+### 7.1 Region
+
+필수:
+
+* `region_id: ID`
+* `geometry: Geometry`
+* `role: "candidate" | "distractor" | "answer" | "object"`
+* `source: "candidate_model" | "inpaint" | "fx" | "manual"`
+* `attributes: JsonDict` (예: 점수, 임베딩, occlusion ratio 등)
+* `version: int` (region 자체 변경 카운트. Scene version과 별개)
+
+선택:
+
+* `linked_object_id?: ID` (ObjectGroup과 연결)
+
+불변/제약:
+
+* geometry 좌표는 background 기준
+* bbox는 이미지 경계를 넘지 않는 것을 권장(필수 여부는 정책)
+
+### 7.2 Geometry (bbox-only)
+
+필수:
+
+* `type: "bbox"`
+* `bbox: BBox`
+
+미래 확장 슬롯(미구현, 저장만 가능):
+
+* `mask_ref?: AssetRef`
+
+### 7.3 BBox
+
+필수:
+
+* `x: float`
+* `y: float`
+* `w: float`
+* `h: float`
+
+의미:
+
+* (x, y)는 좌상단 기준
+* w/h는 양수
+* 단위는 px
+
+---
+
+## 8) ObjectGroup (선택)
+
+### 8.1 ObjectGroup
+
+목적:
+
+* 관계/의미 목표에서 여러 region을 하나의 “개념적 객체”로 묶기 위한 보조 구조
+* 판정은 region 기준이므로 없어도 됨
+
+필수:
+
+* `object_id: ID`
+* `region_ids: ID[]` (해당 Scene.regions에 존재해야 함)
+
+선택:
+
+* `type?: string`
+* `properties?: JsonDict`
+
+---
+
+## 9) Composite
+
+### 9.1 Composite
+
+필수:
+
+* `final_image_ref: AssetRef`
+
+권장(옵션):
+
+* `render_meta?: JsonDict` (합성 파라미터 요약, 레이어 링크 등)
+
+---
+
+## 10) Goal
+
+### 10.1 Goal
+
+필수:
+
+* `goal_type: "relation" | "count" | "shape" | "semantic"`
+* `constraint_struct: JsonDict` (정책 미정. 구조만 담는다)
+* `answer_form: "region_select" | "click_one" | "click_multiple"`
+
+선택:
+
+* `scope_region_ids?: ID[]` (목표 적용 범위를 특정 region 집합으로 제한)
+
+불변:
+
+* Goal은 “검증 가능하도록 구조화된 정보”를 담는다. 문장 여부는 비중요
+
+---
+
+## 11) Answer
+
+### 11.1 Answer
+
+필수:
+
+* `answer_region_ids: ID[]`
+* `uniqueness_intent: true`
+
+제약:
+
+* `answer_region_ids`는 Scene.regions 내 region_id의 부분집합
+* 현재 기본은 단일 정답을 목표로 하나, 수량 목표를 위해 복수 region도 허용
+* 단, 정답 집합 자체는 1개로 수렴해야 함(유일성)
+
+---
+
+## 12) Verification
+
+### 12.1 VerificationBundle
+
+필수:
+
+* `logical: VerificationPart`
+* `perception: VerificationPart`
+* `final: VerificationFinal`
+
+### 12.2 VerificationPart
+
+필수:
+
+* `score: Score`
+* `pass: PassFlag`
+* `signals: JsonDict` (예: 후보 수, 혼동 위험 수치 등. 상세 정책은 비포함)
+
+### 12.3 VerificationFinal
+
+필수:
+
+* `total_score: Score`
+* `pass: PassFlag`
+* `failure_reason: string` (pass면 "" 허용)
+
+제약:
+
+* `failure_reason`는 사람이 읽을 수 있는 요약 문자열
+* 별도의 표준 코드 체계는 추후 확정(현재는 string)
+
+---
+
+## 13) Difficulty
+
+### 13.1 Difficulty
+
+필수:
+
+* `estimated_score: Score`
+* `source: "rule_based" | "learned"`
+
+권장(옵션):
+
+* `calibration_version?: string`
+
+---
+
+## 14) 저장/참조 규칙(최소)
+
+* Scene은 **단일 JSON**으로 직렬화 가능해야 함
+* AssetRef는 다음 중 하나를 지원
+
+  * 로컬 경로(개발)
+  * S3/MinIO 경로(협업)
+  * 기타 URL
+* 권장 디렉토리 규칙(로컬 기준)
+
+  * `artifacts/scenes/{scene_id}/{version_id}/scene.json`
+  * `.../composite.png`
+  * `.../verification.json` (scene.json에서 파생 가능)
+
+---
+
+## 15) 버전 업그레이드 규칙
+
+* 스키마 변경 시 `config_version`과 별도로 `schema_version` 필드 도입 가능
+* v1에서는 schema_version 생략(암묵 v1)
+
+---
+
+## 16) 비목표(명시)
+
+* 세그멘테이션(mask) 계산/판정 로직은 v1에서 구현하지 않는다
+* constraint_struct 내부 구조/정책(임계값/규칙)은 본 문서 범위가 아니다
+* 모델 학습/데이터셋 설계는 본 문서 범위가 아니다
+tmuix

.context/capabilities.md

@@ -0,0 +1,39 @@
+# Discoverex Current Capabilities & Specs
+
+이 문서는 현재 엔진이 실제로 수행할 수 있는 능력과 구체적인 동작 방식, 그리고 제품화를 위해 해결해야 할 기술적 공백을 정의합니다.
+
+## 1. 현재 실행 능력 (Verified Path)
+
+현재 엔진은 오케스트레이션과 인프라 연동 측면에서 아래의 경로를 안정적으로 지원합니다.
+
+- **실행 체인**: `Job Spec -> Prefect Run -> Worker 실행 -> MinIO 저장 -> MLflow 기록`
+- **산출물 보장**: `scene.json`, `verification.json`, `composite.png` 등 캐논 산출물 번들 생성 및 영속화.
+- **운영 모드**: 로컬(Local) 및 워커(Worker) 모드 전환 지원. 워커 모드에서는 MinIO와 원격 MLflow 서버를 사용합니다.
+
+## 2. 생성 파이프라인 (`generate`) 상세 동작
+
+`generate` 명령은 `background_asset_ref`를 입력받아 아래 단계로 동작합니다.
+
+1. **Background 조립**: 입력된 참조(Ref)를 바탕으로 베이스 레이어를 생성합니다. (배경 직접 생성은 미지원)
+2. **Hidden Region 생성**: 배경 이미지에서 오브젝트가 배치될 후보 영역(BBox)을 추론하거나 고정 레이아웃을 사용합니다.
+3. **Region별 Inpaint**: 각 후보 영역을 자연스럽게 메우는 인페인팅을 수행합니다. (현재 프롬프트는 고정 문자열 사용)
+4. **Scene 골격 조립**: 생성된 리전들과 정답(첫 번째 리전으로 고정), 목표(Goal) 정보를 결합하여 `Scene` 객체를 만듭니다.
+5. **Composite / FX**: 최종 결과물을 합성하고 FX 효과를 적용합니다. (현재 일부 모델은 Placeholder PNG를 생성)
+6. **Verification**: 생성된 씬의 논리적/지각적 점수를 측정하고 통과 여부를 판정합니다.
+
+## 3. 기술적 공백 및 제약 사항 (Gaps & Placeholders)
+
+현재 엔진은 "실행 가능한 프레임워크"로서 기능하며, 생성 품질 측면에서는 아래와 같은 Placeholder가 존재합니다.
+
+- **배경 생성 부재**: 텍스트 프롬프트로 배경을 직접 생성하지 않으며, 외부 참조 이미지에 의존합니다.
+- **프롬프트 계획 부재**: 유스케이스(관계, 수량 등)에 따른 세만틱 프롬프트 계획 없이 고정된 문자열을 사용하여 오브젝트를 생성합니다.
+- **최종 렌더링 한계**: FX 단계에서 실제 고품질 합성 대신 기술적 산출물 요건만 충족하는 Placeholder 이미지가 생성될 수 있습니다.
+- **정답 고정 규칙**: 현재는 "추론된 첫 번째 후보가 항상 정답"이라는 파이프라인 규칙을 따릅니다.
+
+## 4. 품질 지표의 의미
+
+최근 검증 실행에서 `scene status=failed`가 발생하는 것은 시스템 오류가 아니라 **품질 게이트(Quality Gate) 탈락**을 의미합니다. 이는 현재 생성 파이프라인의 Placeholder 성격으로 인해 지각적 점수(Perception Score)가 낮게 측정되는 자연스러운 결과입니다.
+
+## 5. 참고 문서
+- 아키텍처 및 도메인 모델: `.context/architecture.md`
+- 상세 캐논 규격: `.context/canon.md`