# Creative Story Prompt Contract Research

작성일: 2026-05-02

이 폴더는 현재 파이프라인을 대체하는 새 구조 제안이 아니다. 이미 프로젝트가 채택한 핵심 방식, 즉 "시나리오를 한 번에 이해시키지 않고 여러 단계로 읽고, 중간 결과를 카드/체크포인트로 축적한 뒤 이미지 프롬프트로 컴파일한다"는 설계를 더 명시적인 prompt I/O 계약으로 정리한 문서다.

## 결론

시나리오 기반 이미지 생성은 일반 문서 분석과 다르다. 인간도 여러 번 읽으며 장면, 인물 상태, 감정 변화, 시공간, 배경, 소품, 카메라 가능성을 머릿속에 재구성한다. 따라서 LLM에게 "이 씬의 샷을 바로 뽑아라"라고 묻는 방식은 불안정하다. 현재 레포처럼 단계별로 나누는 방향이 맞고, 보완할 지점은 단계 수를 줄이는 것이 아니라 각 단계의 입력/출력 계약을 더 좁고 검증 가능하게 만드는 것이다.

핵심 방향은 다음과 같다.

- `facts`: 원문에 명시된 사실
- `inferences`: 원문에서 합리적으로 추론한 시각 정보
- `creative_decisions`: 이미지화를 위해 선택한 연출 판단
- `bindings`: 캐릭터/아웃룩/소품/배경/참조 이미지와 연결되는 ID
- `validation`: 다음 단계가 거부하거나 재시도할 수 있는 기계 검증 조건

이 5가지를 한 프롬프트 안에 섞지 말고, 단계별 카드로 축적한 뒤 마지막 `scene_detail`/image prompt 단계에서만 컴파일해야 한다.

## 문서 목록

| 파일 | 내용 |
|---|---|
| [01_external_research_synthesis.md](./01_external_research_synthesis.md) | 논문, 오픈소스, API 문서에서 얻은 실용적 시사점 |
| [02_current_pipeline_reading.md](./02_current_pipeline_reading.md) | 현재 레포의 실제 플로우를 "여러 번 읽기" 관점으로 재해석 |
| [03_prompt_io_contracts.md](./03_prompt_io_contracts.md) | 단계별 prompt input/output 계약과 JSON shape |
| [04_prompt_templates.md](./04_prompt_templates.md) | 실제 시스템/유저 프롬프트 템플릿 초안 |
| [05_card_storage_and_validation.md](./05_card_storage_and_validation.md) | Card 의미, 저장 위치, checkpoint/DB 분리, 검증 방식 |
| [06_practical_roadmap.md](./06_practical_roadmap.md) | 현실적인 도입 순서와 평가 방법 |
| [problems.md](./problems.md) | 현재 구조에서 prompt 계약 관점의 문제점과 리스크 |

## 전체 구조 다이어그램

```mermaid
flowchart TD
    A[Scenario Text<br/>cleaned + segmented] --> B[Reading Cards<br/>facts / events / relations]
    B --> C[Beat Cards<br/>state changes]
    C --> D[Shot Candidate Cards<br/>one still moment]
    D --> E[Shot Selection Cards<br/>ROI + visual feasibility]
    E --> F[Continuity Cards<br/>fixed scene state]
    E --> G[Background Cards<br/>space + state + floor plan]
    F --> H[Render Prompt Cards<br/>shot + entities + continuity]
    G --> H
    H --> I[Asset Readiness<br/>refs exist and paths valid]
    I --> J[Image Generation]
    J --> K[Visual Validation]
```

중요한 점은 `ShotCard`, `ContinuityCard`, `BackgroundCard`, `RenderPromptCard`가 새로운 거대한 아키텍처가 아니라는 것이다. 현재 파이프라인의 `shot_extract`, `shot_selection`, `scene_consistency`, `background_*`, `scene_detail` 체크포인트를 더 명확한 계약 이름으로 부르는 것이다.

## 기준으로 본 내부 자료

- `README.md`
- `docs/pipeline_flow_v4.md`
- `docs/architecture-easy/00-overview.md`
- `docs/architecture-easy/03-shot-design.md`
- `docs/architecture-easy/04-directing.md`
- `docs/architecture-easy/05-image-making.md`
- `prompts/_base/shot_extract/11.202604201230/system.md`
- `prompts/_base/shot_selection/4.202604191600/system.md`
- `prompts/_base/shot_validator/3.202604301730/system.md`
- `prompts/_base/scene_consistency/5.202605021400/system.md`
- `prompts/_base/scene_detail/12.202605021300/system.md`
- `prompts/_base/background_classify/3.202604300520/system.md`
- `prompts/_base/background_master_plan/1.202604292000/system.md`
- `prompts/_base/floor_plan_prompt/3.202604301041/system.md`
- `prompts/_base/background_prompt/4.202604301033/system.md`

## 외부 자료

- Fountain screenplay syntax: https://fountain.io/syntax/
- Storyboarder: https://github.com/wonderunit/storyboarder
- OpenAI Structured Outputs: https://developers.openai.com/api/docs/guides/structured-outputs
- OpenAI Image Generation: https://developers.openai.com/api/docs/guides/image-generation
- Gemini Structured Outputs: https://ai.google.dev/gemini-api/docs/structured-output
- Gemini Image Generation: https://ai.google.dev/gemini-api/docs/image-generation
- MovieNet: https://researchportal.hkust.edu.hk/en/publications/movienet-a-holistic-dataset-for-movie-understanding/
- MovieGraphs: https://openaccess.thecvf.com/content_cvpr_2018/html/Vicol_MovieGraphs_Towards_Understanding_CVPR_2018_paper.html
- VidSitu: https://vidsitu.org/
- SummScreen: https://huggingface.co/papers/2104.07091
- MovieSum: https://huggingface.co/papers/2408.06281
- TaleCrafter: https://github.com/AILab-CVC/TaleCrafter
- StoryDiffusion: https://storydiffusion.github.io/