BookLeme 튜토리얼: 책 한 권을 설치 및 검증 가능한 Agent Skill로 컴파일하기

BookLeme이란

BookLeme(중문명 “读了么”)는 책을 Agent Skill로 컴파일하는 도구 체인입니다. 일반적인 요약을 생성하는 것이 아니라 책에 담긴 작업 방식을 추출하는 데 중점을 둡니다. 예를 들어 질문 순서, 판단 조건, 증거 규칙, 프로세스 상태와 적용되지 않는 경계를 추출한 뒤 설치·호출·검증할 수 있는 산출물로 구성합니다.

이 프로젝트는 책 처리를 컴파일 단계와 런타임 단계로 나눕니다. 컴파일 시 원본 책을 읽고 처리하며, 런타임에는 생성된 지식 분할을 필요할 때만 로드합니다. 따라서 Skill을 호출할 때마다 책 전체를 다시 읽는 일을 피할 수 있습니다.

주의: “요약이 아닌 구조를 추출한다”는 것은 프로젝트가 채택한 엔지니어링 설계 선택입니다. 그러나 README에서는 이를 프로젝트가 아직 검증하지 않은 가설로 명시하고 있으며, 이미 입증된 결론으로 보지 않습니다.

BookLeme이 생성하는 것

BookLeme은 두 가지 생성 엔진을 제공합니다. 두 엔진은 추출 및 검증 단계의 중간 표현을 공유하고 렌더링 단계에서만 분기하므로, 두 종류의 산출물을 동시에 생성할 때 책을 두 번 처리할 필요가 없습니다.

지식 패키지 knowledge_pack

지식 패키지는 조회 가능한 구조화 지식 베이스로, 주로 Topic Index 라우팅 테이블, 필요할 때 로드하는 프레임워크 분할, 의사결정 빠른 참조표와 출처 목록으로 구성됩니다. “책의 특정 프레임워크를 어떻게 사용하는가”와 같은 질문에 적합합니다.

행동 Skill behavior_skill

행동 Skill은 전체 프로세스를 실행하는 데 사용되며, 역할 정의, 하드 제약, 상태 머신, 명명된 출력 계약, 안티패턴과 감정 안전장치를 포함할 수 있습니다. 지식을 조회하는 데 그치지 않고 코칭 대화와 같은 여러 단계의 작업을 실행하는 데 적합합니다.

핵심 기능

• 두 엔진 자동 라우팅: 12개의 결정적 장르 특성에 따라 지식 패키지 또는 행동 Skill을 선택하며, 엔진을 수동으로 지정할 수도 있습니다.
• 플러그인 방식 장르: 새로운 장르를 추가할 때 핵심 파이프라인을 수정하지 않고 사용자 플러그인 디렉터리에 Python 파일 하나를 추가할 수 있습니다.
• 문자 단위 충실도 재검증: 인용문은 원문의 정확한 부분 문자열이어야 하며 여러 측정 가능한 지표를 통과해야 합니다.
• 저작권 하드 게이트: 설치 및 배포 전에 결정적 저작권 검사를 실행하며, 제3자 도서로 생성된 Skill은 기본적으로 비공개로 유지됩니다.
• 런타임 타사 의존성 제로: 핵심 구현은 Python 표준 라이브러리만 사용합니다.
• 단계별 멱등성: 파이프라인은 SHA-256을 사용해 재실행을 지원합니다. 특정 단계의 산출물을 삭제한 경우 해당 단계만 다시 실행하면 됩니다.

설치 및 환경 준비

BookLeme은 Python 3.9 이상을 요구합니다. 저장소를 클론한 후 Python 모듈 진입점을 통해 바로 실행할 수 있으며, 먼저 타사 런타임 의존성을 설치할 필요가 없습니다.

git clone https://github.com/bookleme/bookleme.git
cd bookleme
python3 -m bookleme --version

명령이 버전 정보를 출력하면 기본 환경을 사용할 수 있는 상태입니다. 저장소는 PDF, EPUB, DOCX, Markdown, HTML, RTF 및 MOBI 등의 입력 형식을 지원한다고 명시합니다. 아래에서는 프로젝트에 포함된 Markdown 합성 원고로 전체 과정을 시연합니다.

첫 번째 컴파일: 원고에서 Skill 생성

run 하위 명령을 실행하고 --input으로 원고를 지정하며 --title로 제목을 설정합니다.

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "나의 첫 번째 책"

기본적으로 BookLeme은 원고의 장르 특성을 분석하고 적합한 생성 엔진을 자동으로 선택합니다. 컴파일 과정은 입력 등록, 텍스트 추출, 중국어 분할, 장르 라우팅, 원자 능력 추출, 충실도 검증, 렌더링, 종합 검증, 설치 및 스모크 평가 등의 단계로 진행됩니다.

권장: 처음 사용한다면 저장소에서 제공하는 합성 테스트 원고를 먼저 사용하세요. 제3자 도서를 처리하기 전에 해당 도서를 사용할 권리가 있는지 확인하고 생성 산출물의 배포 제한을 이해해야 합니다.

생성 엔진 선택

--engine을 사용해 출력 유형을 제어할 수 있습니다.

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "코칭 대화 예시" \
  --engine behavior_skill

사용 가능한 값은 다음과 같습니다.

• auto: 라우터가 자동으로 선택합니다.
• knowledge_pack: 구조화된 지식 패키지만 생성합니다.
• behavior_skill: 실행 가능한 행동 Skill만 생성합니다.
• both: 두 종류의 산출물을 모두 생성합니다.

라우팅을 비활성화하고 두 엔진의 출력을 모두 생성하려면 --no-router를 사용할 수 있습니다.

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "두 엔진 예시" \
  --no-router

장르 플러그인 지정

장르 플러그인은 산출물의 상태 머신, 출력 계약, 하드 제약과 표현 방식을 결정합니다. 현재 구현된 플러그인은 다음과 같습니다.

• coach_dialogue: 코칭 또는 자기 대화에 사용하며, 문답 상태 머신, 감정 안전장치, 중단 및 대화 재개를 지원합니다.
• knowledge_reference: 프레임워크 빠른 참조에 사용하며 Topic Index를 통해 콘텐츠를 라우팅합니다. 책에서 제공하지 않는 정보를 만나면 반드시 답변을 거부해야 합니다.

professional_analysis와 decision_checklist는 아직 후속 M4 로드맵에 속하므로 현재 완료된 기능으로 간주해서는 안 됩니다.

--genre를 사용해 구현된 플러그인을 강제로 선택할 수 있습니다.

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "인생 설계 대화" \
  --engine behavior_skill \
  --genre coach_dialogue

생성 산출물 검증

생성이 완료되면 프로젝트에서 제공하는 검증 명령으로 산출물을 검사해야 합니다. README에서는 examples/coach를 예로 듭니다.

python3 -m bookleme validate examples/coach

이 단계에서는 공식 검증기, 자체 lint와 저작권 하드 게이트를 실행합니다. BookLeme은 충실도를 검사 가능한 지표로 나누며, 인용문 파싱률, 문자 단위 위반률, 부정 사례 답변 거부율, 트리거 단어 적중률, 산출물 규정 준수율, shingle 중복 상한과 커버리율을 포함합니다.

프로젝트는 groundedness 휴리스틱 지표도 유지하지만, README에서는 LLM judge가 아직 연결되지 않았다고 명시합니다. 따라서 현재 이 값은 보고용으로만 사용되며 하드 게이트로 사용되지 않습니다.

회귀 테스트 실행

핵심 코드, 플러그인 또는 템플릿을 수정한 후 전체 테스트를 실행합니다.

python3 -m unittest discover -s tests -v

플러그인을 개발 중이라면 상태 스키마를 확인하고 플러그인 파일을 별도로 검증할 수도 있습니다.

python3 -m bookleme schema --state
python3 -m bookleme plugin validate bookleme/plugins/builtin/coach_dialogue.py

산출물 설치 및 사용 권리 선언

기본적으로 생성 명령은 산출물을 Skill 소스에 기록하지 않습니다. 설치하려면 명시적으로 --install을 추가해야 합니다. 또한 --user-rights를 사용해 입력 콘텐츠의 권리 상태를 선언할 수 있습니다.

python3 -m bookleme run \
  --input path/to/book.md \
  --title "내부 지식 Skill" \
  --engine both \
  --install \
  --user-rights owned

--user-rights는 다음 값을 지원합니다.

• owned: 사용자가 콘텐츠 권리를 보유합니다.
• licensed: 해당 라이선스를 취득했습니다.
• public_domain: 콘텐츠가 퍼블릭 도메인에 속합니다.
• unknown: 권리 상태를 알 수 없습니다.

권리 선언은 법적 판단을 대신할 수 없습니다. MIT 라이선스는 BookLeme 변환기의 코드와 Skill 정의에만 적용되며 입력 도서에는 적용되지 않습니다. 또한 파생 산출물을 배포할 권리를 사용자에게 자동으로 부여하지 않습니다.

저작권 하드 게이트 이해하기

BookLeme의 출력은 구조화된 파생 노트로, 원문을 재현하는 것이 아닙니다. 프로젝트에는 6개의 저작권 하드 게이트가 설정되어 있으며, 어느 하나라도 실패하면 설치 또는 배포가 차단됩니다.

1. 개별 인용문은 150자를 초과하지 않아야 하며 입력 원문에서 문자 단위로 추적할 수 있어야 합니다.
2. 전체 인용 비율은 0.03을 초과하지 않아야 합니다.
3. 연속 복사 콘텐츠는 150자를 초과하지 않아야 합니다.
4. 13자 shingle 중복률은 0.10을 초과하지 않아야 합니다.
5. 산출물에 전체 원문 또는 원본 분할이 포함되어서는 안 됩니다.
6. contains_original_text는 반드시 false여야 합니다.

제3자 도서로 생성된 Skill은 기본적으로 비공개이며 배포할 수 없습니다. 공개 배포 권리를 실제로 보유한 경우에도 다음 두 가지 확인 매개변수를 명시적으로 제공해야 합니다.

--public --confirm-public PUBLISH

공개 매개변수는 엔지니어링 확인 게이트일 뿐 저작권 허가와는 다릅니다. 사용자는 여전히 라이선스 범위, 적용 법률과 입력 자료의 권리 상태를 직접 확인해야 합니다.

고급 팁: 단계별 멱등성을 활용한 재실행

BookLeme의 S0부터 S9까지의 파이프라인은 단계별 멱등성으로 설계되었으며 SHA-256을 사용해 기존 결과를 식별합니다. 장문의 문서 처리가 예기치 않게 중단되면 이미 완료된 단계의 산출물을 보존할 수 있습니다. 특정 단계의 출력만 삭제하면 도구가 해당 단계만 다시 실행하므로 책 전체를 다시 처리할 필요가 없습니다.

이 설계는 플러그인이나 렌더링 로직을 디버깅할 때도 유용합니다. 두 엔진은 앞선 추출, 분할, 능력 추출과 충실도 검증 결과를 공유하므로 렌더링 계층을 수정할 때 원고를 다시 읽을 필요가 없습니다.

고급 팁: 사용자 지정 장르 플러그인 개발

사용자 지정 플러그인은 bookleme/plugins/user/<genre_id>.py에 배치해야 합니다. 프로젝트는 플러그인이 핵심 필드를 선언하도록 요구하며, 필수 필드가 없으면 로드를 거부합니다.

• state_machine: 프로세스 상태와 전환을 정의합니다.
• output_contract: 산출물이 제공해야 하는 출력을 정의합니다.
• hard_constraints: 위반할 수 없는 규칙을 정의합니다.
• anti_patterns: 피해야 할 잘못된 행동을 나열합니다.
• voice_calibration: 말투, 호칭, 금지어와 결론의 귀속을 정의합니다.
• copyright_profile: 저작권 제어와 관련된 설정을 선언합니다.
• trigger_words: 중국어 트리거 단어 3~5개를 제공합니다.
• eval_prompts: 평가 프롬프트를 제공하며, 그중 하나 이상은 부정 사례여야 합니다.

플러그인을 작성하기 전에 플러그인 사양을 읽는 것이 좋습니다. 작성이 끝나면 plugin validate를 사용해 검증하세요. 플러그인을 통해 충실도 검사, 저작권 하드 게이트 또는 부정 사례 답변 거부 요구를 우회해서는 안 됩니다.

S0–S9 파이프라인 작동 방식

1. S0–S2: 입력을 등록하고, 결정론적으로 추출한 뒤 정규화하여 중국어 단위로 분할합니다. 고정된 영어 Chapter 표기에 의존하지 않습니다.
2. S3: 12개 특성에 따라 장르를 라우팅하며, 모호한 경우 두 엔진을 자동으로 선택할 수 있습니다.
3. S4: 원자적 역량을 추출합니다. 결정론적 추출기와 선택적 OpenAI 호환 LLM 추출기를 사용할 수 있으며, 설정이 없으면 자동으로 대체 경로를 사용합니다.
4. S5: 인용문을 한 글자씩 검증하고 claim ledger를 유지하며 충실도 지표를 계산합니다.
5. S6: 플러그인에 따라 지식 패키지 또는 행동 Skill을 렌더링합니다. 두 엔진이 실제로 분기되는 지점입니다.
6. S7–S9: 종합 검증, 멱등 설치 및 스모크 평가를 실행합니다.

S3과 S4는 모두 S2의 결과를 입력으로 사용하며 병렬로 작업할 수 있습니다. 두 엔진은 S1, S2, S4, S5의 중간 표현을 공유하여 중복 읽기와 추출을 방지합니다.

실무 권장 사항

• 먼저 프로젝트에 포함된 합성 원고로 명령어 사용법을 익힌 다음 실제 책을 처리하세요.
• 산출물 유형이 확실하지 않으면 --engine auto를 사용하세요. 두 결과를 동시에 비교하려면 both 또는 --no-router를 사용하세요.
• 플러그인이나 템플릿을 수정할 때마다 산출물 검증과 단위 테스트를 실행하세요.
• 책에 제공되지 않은 정보에 대해서는 답변을 거부할 수 있어야 하며, 모델의 상식으로 출처의 공백을 채우지 마세요.
• 책 원문, 표지 또는 스캔본을 저장소에 커밋하지 말고, 기본적으로 비공개인 타사 도서 산출물을 그대로 공개하지 마세요.
• 충실도 문서와 저작권 문서를 읽고 지표와 공개 범위를 확인하세요.

현재 범위

BookLeme은 현재 M0–M3 단계에 있습니다. coach_dialogue와 knowledge_reference는 구현되었지만, 전문 분석 및 의사결정 체크리스트 플러그인은 아직 후속 로드맵에 있습니다. LLM judge는 아직 연동되지 않았으며, 일부 관련 지표는 여전히 null입니다. 사용할 때는 이미 구현된 기능, 실제 테스트가 완료된 기능, 아직 검증이 필요한 기능을 구분해야 합니다.

맺음말

BookLeme은 “독서”를 테스트 가능한 엔지니어링 파이프라인으로 전환합니다. 먼저 추출하고 분할한 다음 역량을 추출하고 충실도를 검증하며, 마지막으로 지식 패키지 또는 행동 Skill로 렌더링합니다. 최초 컴파일을 완료한 후에는 책의 방법을 재사용하면서도 출처의 경계와 검증 가능성을 유지할 수 있도록 검증, 테스트, 권리 고지 및 저작권 검사를 정해진 절차에 포함하는 것이 좋습니다.