AI Pipeline

이 저장소는 소설 텍스트를 이벤트/인물/관계/관점 데이터로 변환하는 파이프라인입니다.

주요 기능

• 이벤트 추출: chapter 텍스트에서 사건 단위를 추출해 out/, out_debug/ 생성
• 이벤트 병합: raw 이벤트를 서사 단위로 압축해 out_merged/, out_merged_debug/ 생성
• 코리퍼런스: merged 이벤트 기준 대명사/지시어 해소(out_coref_merged/)
• 전역 캐릭터 레지스트리: book-wide 인물 ID/alias 통합(out_book_characters/)
• 챕터 캐릭터 맵: 챕터별 등장 캐릭터 ID 매핑(out_chapter_character_maps/)
• 관계 추출: 이벤트 단위 인물 관계(from/to, label, positivity) 생성(out_relationships/)
• 관점 요약: 챕터 단위 인물 관점 요약 생성(out_perspectives/)

스크립트 요약

• scripts/extract_events.py: 이벤트 추출
• scripts/merge_events.py: 이벤트 병합
• scripts/coref_events.py: 코리퍼런스(merged 기준)
• scripts/build_book_characters.py: 전역 캐릭터 레지스트리 생성
• scripts/build_chapter_character_maps.py: 챕터별 캐릭터 매핑 생성
• scripts/extract_relationships.py: 이벤트별 관계 추출
• scripts/extract_perspectives.py: 챕터별 관점 요약
• scripts/normalize_characters.py: 챕터 로컬 캐릭터 정규화(검수/비교용)

프롬프트 파일

• prompts/relationships_system.txt
• prompts/relationships_user.txt

참고 문서

• docs/pipeline_outputs.md: 산출물 생성 순서, 입력/출력 의존성, 디버그 파일 해석 가이드

출력 폴더 역할

• out/: 업로드용 이벤트(5필드)
• out_debug/: 이벤트 디버그(evidence/entities)
• out_merged/, out_merged_debug/: 병합 이벤트 및 추적 정보
• out_coref_merged/: 코리퍼런스 결과
• out_book_characters/: 전역 인물 마스터
• out_chapter_character_maps/: 챕터별 등장 전역 인물 맵
• out_relationships/, out_relationships_debug/: 관계 추출 결과
• out_perspectives/, out_perspectives_debug/: 관점 요약 결과
• out_characters/, out_characters_debug/: 챕터 로컬 인물 결과(보조)

실행 기본 원칙

• API 키는 .env의 GEMINI_API_KEY 사용
• 실행 시 --root를 대상 책 폴더로 지정
• 부분 실행(--start_chapter, --end_chapter) 가능

실행 예시

아래 예시는 책 루트가 ebook/6d530286-a9f7-420a-a898-95eea431308c인 경우를 기준으로 한다.

0. 환경 변수 로드

set -a
source .env
set +a

1. raw 이벤트 추출

python3 scripts/extract_events.py \
  --root ebook/6d530286-a9f7-420a-a898-95eea431308c \
  --start_chapter 1 \
  --end_chapter 30

생성:

• out/chapter_XXX_events.json
• out_debug/chapter_XXX_events_debug.json

2. 이벤트 병합

python3 scripts/merge_events.py \
  --root ebook/6d530286-a9f7-420a-a898-95eea431308c \
  --start_chapter 1 \
  --end_chapter 30 \
  --input_dir out_debug \
  --output_dir out_merged \
  --debug_output_dir out_merged_debug

생성:

• out_merged/chapter_XXX_events_merged.json
• out_merged_debug/chapter_XXX_events_merged_debug.json

3. 코리퍼런스 해소

python3 scripts/coref_events.py \
  --root ebook/6d530286-a9f7-420a-a898-95eea431308c \
  --start_chapter 1 \
  --end_chapter 30 \
  --input_dir out_merged_debug \
  --output_dir out_coref_merged

생성:

• out_coref_merged/chapter_XXX_events_coref.json

4. 전역 캐릭터 레지스트리 생성

python3 scripts/build_book_characters.py \
  --root ebook/6d530286-a9f7-420a-a898-95eea431308c \
  --start_chapter 1 \
  --end_chapter 30

생성:

• out_book_characters/book_characters_0.json

5. 관계 추출

python3 scripts/extract_relationships.py \
  --root ebook/6d530286-a9f7-420a-a898-95eea431308c \
  --start_chapter 1 \
  --end_chapter 30 \
  --input_events_dir out_merged_debug \
  --input_coref_dir out_coref_merged \
  --book_characters_path out_book_characters/book_characters_0.json \
  --output_dir out_relationships \
  --debug_output_dir out_relationships_debug

생성:

• out_relationships/chapter_XXX_relationships_event_YYYY.json
• out_relationships_debug/chapter_XXX_relationships_event_YYYY.json

6. 관점 요약

python3 scripts/extract_perspectives.py \
  --root ebook/6d530286-a9f7-420a-a898-95eea431308c \
  --start_chapter 1 \
  --end_chapter 30 \
  --input_events_dir out_merged_debug \
  --input_coref_dir out_coref_merged \
  --book_characters_path out_book_characters/book_characters_0.json \
  --output_dir out_perspectives \
  --debug_output_dir out_perspectives_debug

생성:

• out_perspectives/chapter_XXX_perspective_summaries_Ko.json
• out_perspectives_debug/chapter_XXX_perspective_summaries_debug.json

7. 챕터 로컬 인물 정규화

python3 scripts/normalize_characters.py \
  --root ebook/6d530286-a9f7-420a-a898-95eea431308c \
  --start_chapter 1 \
  --end_chapter 30 \
  --input_dir out_merged_debug

생성:

• out_characters/chapter_XXX_characters_0.json
• out_characters_debug/chapter_XXX_characters_debug.json

8. 전체 파이프라인 순서 요약

set -a
source .env
set +a

python3 scripts/extract_events.py --root ebook/6d530286-a9f7-420a-a898-95eea431308c --start_chapter 1 --end_chapter 30
python3 scripts/merge_events.py --root ebook/6d530286-a9f7-420a-a898-95eea431308c --start_chapter 1 --end_chapter 30
python3 scripts/coref_events.py --root ebook/6d530286-a9f7-420a-a898-95eea431308c --start_chapter 1 --end_chapter 30 --input_dir out_merged_debug --output_dir out_coref_merged
python3 scripts/build_book_characters.py --root ebook/6d530286-a9f7-420a-a898-95eea431308c --start_chapter 1 --end_chapter 30
python3 scripts/extract_relationships.py --root ebook/6d530286-a9f7-420a-a898-95eea431308c --start_chapter 1 --end_chapter 30 --input_events_dir out_merged_debug --input_coref_dir out_coref_merged --book_characters_path out_book_characters/book_characters_0.json
python3 scripts/extract_perspectives.py --root ebook/6d530286-a9f7-420a-a898-95eea431308c --start_chapter 1 --end_chapter 30 --input_events_dir out_merged_debug --input_coref_dir out_coref_merged --book_characters_path out_book_characters/book_characters_0.json

9. 특정 단계만 다시 실행하는 예시

관계만 다시 뽑고 싶을 때:

python3 scripts/extract_relationships.py \
  --root ebook/6d530286-a9f7-420a-a898-95eea431308c \
  --start_chapter 12 \
  --end_chapter 12 \
  --input_events_dir out_merged_debug \
  --input_coref_dir out_coref_merged \
  --book_characters_path out_book_characters/book_characters_0.json

관점 요약만 다시 뽑고 싶을 때:

python3 scripts/extract_perspectives.py \
  --root ebook/6d530286-a9f7-420a-a898-95eea431308c \
  --start_chapter 12 \
  --end_chapter 12 \
  --input_events_dir out_merged_debug \
  --input_coref_dir out_coref_merged \
  --book_characters_path out_book_characters/book_characters_0.json

이벤트 병합만 다시 하고 싶을 때:

python3 scripts/merge_events.py \
  --root ebook/6d530286-a9f7-420a-a898-95eea431308c \
  --start_chapter 12 \
  --end_chapter 12 \
  --input_dir out_debug

실제 출력 경로 예시

현재 프로젝트에서 파이프라인 출력은 아래 책 루트 하위에 생성됩니다.

• ebook/6d530286-a9f7-420a-a898-95eea431308c/

해당 경로 아래 주요 출력 폴더:

• ebook/6d530286-a9f7-420a-a898-95eea431308c/out/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_debug/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_merged/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_merged_debug/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_coref_merged/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_book_characters/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_chapter_character_maps/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_relationships/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_relationships_debug/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_perspectives/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_perspectives_debug/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_characters/
• ebook/6d530286-a9f7-420a-a898-95eea431308c/out_characters_debug/