# 02. Current Pipeline Reading

이 문서는 현재 레포를 "시나리오를 여러 번 읽는 시스템"으로 재해석한다. 목적은 새 플로우를 주장하는 것이 아니라, 현재 플로우가 왜 이렇게 분리되어야 하는지와 어디에 prompt I/O 계약을 더 명시해야 하는지 정리하는 것이다.

## 현재 제품 목적

현재 제품은 시나리오 PDF를 입력받아 다음을 만든다.

- 인물/장소/소품 카드
- 선택된 웹북용 still shot
- 인물/의상/소품 참조 이미지
- 배경/floor plan/chain background
- 최종 scene image
- 검수 가능한 webbook/PDF 결과물

즉 목표는 "시나리오 요약"이 아니라 "시나리오를 이미지 제작 가능한 shot/card/asset 계약으로 변환"하는 것이다.

## 현재 파이프라인을 읽기 단계로 보면

```mermaid
flowchart TD
    A[text_cleanup] --> B[scene_segmentation]
    B --> C[scene_summary]
    B --> D[beat_extract]
    D --> E[shot_extract]
    E --> F[shot_validator]
    F --> G[shot_selection]
    F --> H[entity extraction]
    H --> I[entity merge / relation / detail / t2i]
    G --> J[scene_director / shot_director]
    J --> K[outlook phases]
    G --> L[shot_dependency / shot_staging]
    L --> M[scene_consistency]
    G --> N[background_*]
    M --> O[scene_detail]
    N --> O
    I --> P[ref_image_gen]
    O --> Q[scene_image_pipeline]
    P --> Q
```

## 읽기 Pass 분류

| Pass | 현재 step | 실제 의미 |
|---|---|---|
| 구조 읽기 | `text_cleanup`, `scene_segmentation` | PDF를 scene 단위로 안정화한다. |
| 서사 읽기 | `scene_summary`, `episode_summary`, `visual_world_rules` | 전체 작품의 톤, 세계, 사건 흐름을 만든다. |
| 사건 읽기 | `beat_extract` | 상태 변화 단위를 찾는다. |
| 시각 순간 읽기 | `shot_extract`, `shot_validator` | 한 장의 still로 가능한 순간 후보를 만든다. |
| 제작 선택 | `shot_selection` | 모든 후보 중 실제 생성할 shot만 선택한다. |
| 엔티티 읽기 | `entity_*`, `outlook_*` | 인물/장소/소품/의상을 ID로 canon화한다. |
| 연출 읽기 | `scene_director`, `shot_director`, `shot_dependency`, `shot_staging` | 누가 보이고, 어떤 상태이며, 어떤 프레이밍인지 결정한다. |
| 연속성 읽기 | `scene_consistency` | 여러 shot에서 변하지 않는 상태를 고정한다. |
| 공간 읽기 | `background_classify`, `background_master_plan`, `floor_plan_prompt`, `background_prompt`, `background_render` | 배경을 독립 asset으로 만든다. |
| 프롬프트 컴파일 | `scene_detail` | 위 결정들을 최종 T2I prompt로 변환한다. |
| 이미지 검증 | `ref_image_gen`, `scene_image_pipeline`, `t2i_review` | 참조/씬 이미지를 만들고 결과를 검수한다. |

## 현재 설계의 중요한 장점

### 1. Shot을 직접 묻지 않는다

현재 `shot_extract`는 `beat_extract` 이후에 실행되고, `shot_selection`은 별도다. 이게 맞다. raw scene text에서 바로 "좋은 shot 3개"를 묻는 방식은 다음 문제를 만든다.

- 중요한 전환점 누락
- 대사 속 간접 정보 누락
- 지나가는 시각적으로 예쁜 순간 과대 선택
- dead body, 부상, prop 위치 같은 continuity 누락

현재 구조는 "많이 뽑고, 검증하고, 적게 선택"한다. 이 방식이 현실적이다.

### 2. 배경을 scene prompt 안에 섞지 않는다

현재 `background_*` 계열은 selected shot에 맞춰 floor plan, background state, chain background를 따로 만든다. 이 방향도 맞다. 같은 공간을 매 shot마다 prompt로 새로 설명하면 모델이 매번 다른 방을 그린다.

### 3. 사람 검수 가능한 checkpoint가 있다

체크포인트는 단순 캐시가 아니라 creative decision log다. `manifest.json` 단위로 저장되는 결과가 있기 때문에 다음이 가능하다.

- 어느 단계에서 잘못된 해석이 생겼는지 역추적
- 특정 단계만 force 재실행
- human edit 보존
- DB sync 전 산출물 검증

## 지금 더 명시해야 하는 부분

현재 구조의 방향은 맞지만, prompt contract 관점에서 다음은 더 명확해져야 한다.

### 1. Evidence와 creative decision 분리

현재 일부 prompt는 "원문 기반"을 말하지만 출력 schema에 evidence를 강제하지 않는다. 그러면 LLM이 합리적 추론과 임의 창작을 섞어도 다음 단계가 구분하지 못한다.

권장:

```json
{
  "source_facts": [],
  "visual_inferences": [],
  "creative_decisions": [],
  "uncertainties": []
}
```

모든 단계에 다 넣을 필요는 없다. 하지만 `scene_consistency`, `background_master_plan`, `scene_detail`처럼 후속 이미지에 큰 영향을 주는 단계는 최소한 decision reason과 evidence ref가 필요하다.

### 2. Card ownership을 명시

동일한 정보를 여러 step이 동시에 수정하면 drift가 생긴다.

| 정보 | 소유자 | 다른 step의 역할 |
|---|---|---|
| 한 찰나 여부 | `shot_extract` + `shot_validator` | 수정하지 않고 참조 |
| 선택 여부 | `shot_selection` | downstream은 selected만 소비 |
| 인물 등장 여부 | `shot_director` | `scene_detail`은 임의 추가 금지 |
| 고정 자세/상태 | `scene_consistency` | `scene_detail`은 통합만 수행 |
| background state | `background_master_plan` | `background_prompt`는 묘사만 수행 |
| floor plan layout | `floor_plan_prompt/render` | background prompt는 top-down 복제 금지 |
| final T2I syntax | `scene_detail` | image pipeline은 ref binding/translation만 수행 |

### 3. Prompt output과 DB 제약 동기화

Schema가 `string`이라고 해도 DB 컬럼이 `String(32)`면 실패한다. `variant_label`, `state_label`, `bg_id`, `asset_type`, `file_path`는 prompt schema와 DB schema가 함께 계약되어야 한다.

### 4. Asset readiness 단계가 필요

이미지 생성 prompt가 아무리 맞아도 참조 이미지가 없거나 경로가 틀리면 실패한다. 따라서 image generation 전 deterministic validator가 필요하다.

```mermaid
flowchart LR
    A[RenderPromptCard] --> B[Reference Resolver]
    B --> C{All required assets exist?}
    C -->|yes| D[Image Generation]
    C -->|no| E[Blocked / partial<br/>with missing refs report]
```

이 단계는 LLM이 아니라 코드 검증이어야 한다.

## 현재 prompt별 해석

### shot_extract

현재 prompt는 "한 Shot = 1/1000초", "상한 없음", "의상 금지", "ID 금지"를 강하게 준다. 이건 좋다. 이 단계는 최종 제작 선택을 하지 않고 후보를 풍부하게 만든다.

보완점:

- `source_span` 또는 `evidence_ref`가 출력에 있으면 후속 검증이 쉬워진다.
- dynamic motion을 freeze할 때 `motion_direction`을 별도 field로 뽑으면 scene_detail이 덜 흔들린다.

### shot_selection

현재 prompt는 ROI, narrative weight, visual expressibility, 2중 cap을 사용한다. 이건 현실적이다.

보완점:

- 선택하지 않은 high narrative/low visual shot의 `replacement_strategy`를 남기면 scene_detail이 "부분 포커싱/회피"를 더 안정적으로 수행한다.
- `selection_reason`만으로는 부족할 때 `must_preserve_story_function`이 필요하다.

### scene_consistency

현재 prompt는 dead/sleep/injury 같은 고정 상태와 framing별 applies_to_shots 분리를 다룬다. 이건 중요한 개선 방향이다.

보완점:

- `fixed_element`가 어떤 shot에 들어가고 어떤 shot에는 빠지는지 deterministic하게 검증해야 한다.
- `character_state`는 character ID binding을 별도 field로 보관하고, description에는 보통명사만 두는 현재 방식이 타당하다.

### background_*

현재 prompt들은 background strategy, master plan, floor plan, background prompt를 분리한다. 이 방향이 맞다.

보완점:

- `state_label` 길이와 DB 저장 제약을 schema에서 제한하거나 DB를 넓혀야 한다.
- `applies_to_shots`는 selected shot subset과 일치해야 한다.
- scene_detail은 chain_bg reference가 붙을 때 background objects를 새로 생성하도록 지시하면 안 된다.

### scene_detail

현재 prompt는 매우 많은 안전장치를 갖고 있다. 특히 C##/C##O##, close framing, body-part closeup, reference background, prop 본체 visible, physical consistency 같은 실제 실패 대응 규칙이 많이 들어 있다.

보완점:

- 시스템 prompt는 C##O## 직접 사용을 요구하지만 schema description은 bare C##만 사용하라고 말한다. 이 충돌은 prompt contract 관점에서 반드시 정리해야 한다.
- 현재 scene_detail은 너무 많은 규칙을 한 프롬프트에 가진다. 규칙 자체를 줄이기보다, upstream cards가 더 명확하면 scene_detail prompt가 "판단"보다 "컴파일"에 집중할 수 있다.

## 권장 mental model

현재 파이프라인의 목적을 다음처럼 정의하면 혼선이 줄어든다.

```text
The pipeline is not asking an LLM to imagine final images.
The pipeline is building production cards from a screenplay.
Final prompts are compiled from those cards.
Image generation is only the last renderer.
```