JibPil — 소설 집필 보조 도구

회차 본문을 분석해 인물·사건·관계·세계관 정보를 그래프 DB에 저장하고, 다음 회차 집필 시 일관성 있는 컨텍스트를 AI 에이전트에게 제공하는 CLI 도구입니다.

주요 기능

• 회차 본문 → LLM 분석 → 인물 / 장소 / 사건 / 관계 / 세계관 규칙 자동 추출
• 아이젠틱 멀티턴: LLM이 분석 중 필요한 엔티티·이전 회차 원고를 직접 요청
• 이전 회차 누적 데이터를 컨텍스트로 주입해 일관된 엔티티 추출
• NetworkX 기반 그래프 DB에 엔티티와 관계 저장 및 중복 해결
• YAML 프론트매터 + 회차별 섹션 + 교차 링크가 포함된 마크다운 위키 자동 생성
• 타임라인 충돌 감지 및 미해결 복선 추적
• 집필 컨텍스트를 텍스트/JSON 형식으로 출력
• AI 에이전트(tool use) 연동용 Python API 제공
• Claude / OpenAI / Gemini / Ollama / LM Studio / Gemini CLI 멀티 프로바이더 지원

---

설치

Python 3.12 이상과 uv가 필요합니다.

git clone <repo-url>
cd jibpil
uv sync

설치 후 jibpil 명령어를 바로 사용할 수 있습니다.

jibpil --help

---

빠른 시작

아래 순서대로 실행하면 기본 워크플로우를 체험할 수 있습니다.

1. 새 프로젝트 초기화

jibpil new "나의 웹소설"

현재 디렉토리에 .jibpil/ 폴더가 생성됩니다.

2. 회차 등록

jibpil add-episode --ep 1 --file ./ep01.txt

3. 회차 분석

jibpil analyze --ep 1
jibpil analyze --ep 2 --provider gemini-cli

LLM이 본문을 분석하여 그래프 DB와 위키를 업데이트합니다.

4. 위키 확인

jibpil wiki character 홍길동

5. 집필 어시스트

# 텍스트 형식
jibpil assist --ep 2

# JSON 형식 (AI 에이전트에 전달 시)
jibpil assist --ep 2 --format json

---

CLI 커맨드 레퍼런스

커맨드	설명	예시
new <title>	새 JibPil 프로젝트 초기화	jibpil new "천마신교"
add-episode	회차 본문 파일을 프로젝트에 등록	jibpil add-episode --ep 1 --file ./ep01.txt
analyze	회차를 분석해 그래프 DB·위키 업데이트	jibpil analyze --ep 1
wiki <category> <name>	위키 문서 출력	jibpil wiki character 홍길동
assist	다음 회차 집필용 컨텍스트 출력	jibpil assist --ep 2 --format json
graph	관계 그래프를 Mermaid 형식으로 출력	jibpil graph --type relationship

카테고리 목록: character / location / event / item / faction / world_rule / theme

---

AI 에이전트 연동

JibPilAgent는 외부 AI 에이전트가 JibPil 데이터를 tool use 방식으로 조회할 수 있도록 설계된 Python API입니다.

from jibpil.storage.networkx_store import NetworkXStore
from jibpil.storage.wiki_store import WikiStore
from jibpil.analyzer.llm_client import ClaudeClient
from jibpil.agent.api import JibPilAgent

# 스토어 초기화
graph = NetworkXStore(data_path=".jibpil/graph.json")
graph.load()
wiki = WikiStore(wiki_path=".jibpil/wiki")
llm = ClaudeClient()

agent = JibPilAgent(graph=graph, wiki=wiki, llm_client=llm)

# 집필 컨텍스트 조회 (dict 반환)
ctx = agent.get_writing_context(episode=5, recent_n=3)

# 집필 컨텍스트 조회 (프롬프트 블록 반환)
prompt = agent.get_writing_context_as_prompt(episode=5, max_chars=3000)

# 인물 조회
char = agent.query_character("홍길동")

# 관계 조회
rels = agent.find_relationships("홍길동")

# 세계관 규칙 위반 검사
result = agent.validate_against_worldrules("초능력자가 낮에 마법을 사용했다.")
# {"valid": False, "violations": [...]}

# tool_use 핸들러로 직접 사용
response = agent.handle_tool_call(
    "get_writing_context",
    {"episode": 5, "recent_n": 3}
)

agent/tools.py에는 Anthropic tool use 스키마 정의가 포함되어 있어 Claude API의 tools 파라미터에 바로 전달할 수 있습니다.

---

아키텍처 개요

사용자 입력 (회차 본문)
        │
        ▼
  ┌─────────────┐
  │   CLI (cli) │  ← typer 기반 커맨드라인 인터페이스
  └──────┬──────┘
         │
         ▼
  ┌─────────────────┐
  │ IngestPipeline  │  ← 분석 → 저장 오케스트레이션
  │   (pipeline)    │
  └──────┬──────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌──────────┐  ┌──────────────┐
│ Analyzer │  │EntityResolver│  ← LLM 호출, 엔티티 중복 해결
│(analyzer)│  │  (analyzer)  │
└────┬─────┘  └──────┬───────┘
     │               │
     ▼               ▼
  ┌──────────────────────────┐
  │   Storage                │
  │  NetworkXStore (graph)   │  ← 그래프 DB (노드 + 엣지)
  │  WikiStore    (wiki)     │  ← 마크다운 위키
  └──────────────────────────┘
         │
         ▼
  ┌─────────────────┐
  │ ContextBuilder  │  ← 집필 컨텍스트 조립
  │   (context)     │
  └──────┬──────────┘
         │
         ▼
  ┌─────────────────┐
  │  JibPilAgent    │  ← AI 에이전트 연동 API
  │    (agent)      │
  └─────────────────┘

---

개발 환경 설정

# 의존성 설치 (dev 포함)
uv sync --group dev

# 린트
uv run ruff check src/ tests/
uv run ruff format src/ tests/

# 테스트
uv run pytest

# 특정 테스트만 실행
uv run pytest tests/test_pipeline_ingest.py -v

---

LLM 프로바이더 설정

JibPil은 여러 LLM 프로바이더를 지원합니다. JIBPIL_LLM_PROVIDER 환경변수로 선택합니다.

프로바이더	JIBPIL_LLM_PROVIDER 값	필요 키	기본 모델
Anthropic Claude	claude (기본값)	ANTHROPIC_API_KEY	claude-haiku-4-5-20251001
OpenAI GPT	openai	OPENAI_API_KEY	gpt-4o-mini
Google Gemini (API)	gemini	GOOGLE_API_KEY	gemini-2.0-flash
Google Gemini CLI	gemini-cli	gemini CLI 설치 필요	gemini-2.5-pro-preview
Ollama (로컬)	ollama	없음	llama3.2
LM Studio (로컬)	lmstudio	없음	local-model

예시

# Claude (기본값)
export ANTHROPIC_API_KEY="sk-ant-..."
jibpil analyze --ep 1

# OpenAI GPT
export JIBPIL_LLM_PROVIDER=openai
export OPENAI_API_KEY="sk-..."
jibpil analyze --ep 1

# Google Gemini
export JIBPIL_LLM_PROVIDER=gemini
export GOOGLE_API_KEY="AIza..."
jibpil analyze --ep 1

# Ollama (로컬, http://localhost:11434 실행 필요)
export JIBPIL_LLM_PROVIDER=ollama
export OLLAMA_MODEL=mistral      # 선택사항, 기본값: llama3.2
jibpil analyze --ep 1

# LM Studio (로컬, http://localhost:1234 실행 필요)
export JIBPIL_LLM_PROVIDER=lmstudio
export LMSTUDIO_MODEL=my-model   # LM Studio에서 로드된 모델명
jibpil analyze --ep 1

# Gemini CLI (npm install -g @google/generative-ai-cli 설치 필요)
export JIBPIL_LLM_PROVIDER=gemini-cli
export GEMINI_CLI_MODEL=gemini-2.5-pro-preview   # 선택사항
jibpil analyze --ep 1

모델 변경

# 모델만 바꾸고 싶을 때
export JIBPIL_LLM_MODEL=claude-opus-4-6
export JIBPIL_LLM_PROVIDER=claude
jibpil analyze --ep 1

환경변수 전체 목록

변수	설명
JIBPIL_LLM_PROVIDER	LLM 프로바이더 선택: claude / openai / gemini / ollama / lmstudio (기본값: claude)
JIBPIL_LLM_MODEL	사용할 모델명 (기본값: 각 프로바이더의 기본 모델)
ANTHROPIC_API_KEY	Anthropic Claude API 키
OPENAI_API_KEY	OpenAI API 키
GOOGLE_API_KEY	Google Gemini API 키
OLLAMA_MODEL	Ollama 모델명 (기본값: llama3.2)
OLLAMA_BASE_URL	Ollama 서버 URL (기본값: http://localhost:11434/v1)
LMSTUDIO_MODEL	LM Studio 모델명 (기본값: local-model)
LMSTUDIO_BASE_URL	LM Studio 서버 URL (기본값: http://localhost:1234/v1)
GEMINI_CLI_MODEL	Gemini CLI 모델명 (기본값: gemini-2.5-pro-preview)
GEMINI_CLI_PATH	gemini CLI 실행 경로 (기본값: gemini)
GEMINI_CLI_TIMEOUT	CLI 타임아웃 초 (기본값: 300)