Python 파이프라인 (7)¶
NERV에는 서브에이전트 정의와 별개로, scripts/에서 실행되는 Python 주도 파이프라인 7개가
있다. Python이 파일 변환·API 조회·정합성 검사·랭킹 같은 재현 가능한 절차를 조율하고,
문서 품질 심층 검토·인용 추출 보강·외부 후보 평가처럼 해석이 필요한 일부 단계에서만 Claude나 Codex를 호출한다.
- 미사토 · Operations (6) — 논문 PDF를 구조화된 Markdown으로 변환하는 문서 처리 파이프라인.
- 리츠코 · Project Command (1) — 외부 에이전트를 자율 탐색·평가하는 주간 GitHub Hunter.
캐릭터·역할 체계는 4 · 캐릭터, LLM 서브에이전트 39개는 5 · 서브에이전트를 참고하세요.
미사토 · Operations — 문서 처리 파이프라인 (6)¶
PDF로 들어온 논문을 변환·검증하고 메타데이터를 보강하여 분석 가능한 형태로 만든 뒤, 지식 관리(레이)와 탐색(카오루) 역할로 핸드오프하는 파이프라인이다(오케스트레이터 1 + 실행 단위 5).
1. pipeline-orchestrator¶
- 기능 — 문서 처리 5개 실행 단위를 조율하고 단계별 품질 게이트를 적용하는 오케스트레이터.
- 핵심 단계
- 입력 PDF 큐 수집 및 출력 프로파일 결정(
pi/discovered). 실행 계약은produce의warn_and_flag정책을 따름. - 하위 모듈 디스패치: 변환 → 품질 검사 → DOI/KCI → 인용·도표 추출(DOI 처리 후 인용·도표 추출은 병렬로 실행될 수 있음).
- 단계별 산출물 집계 및 다운스트림 핸드오프 페이로드 구성.
2. pdf-to-markdown¶
- 기능 —
marker-pdf기반으로 PDF를 구조 보존 Markdown으로 변환(GPU/MPS 가속, CPU 폴백). - 핵심 단계
- PDF 레이아웃 분석(헤딩·문단·표·수식 영역 탐지).
- 텍스트·구조 추출 후 Markdown 직렬화.
- frontmatter 정규화 및 산출 파일 기록.
3. conversion-quality-checker¶
- 기능 — 변환 결과의 품질 점수를 산출하고 임계값 게이트로 통과 여부를 판정.
- 핵심 단계
- 텍스트 보존율·구조 정합성·노이즈 지표 측정.
conversion_quality점수(0.0~1.0) 산출.- 임계값 0.7 미달 시 경고와 수동 검토 플래그를 기록하고 후속 단계를 계속 실행.
4. doi-resolver¶
- 기능 — 논문 메타데이터를 Crossref에서 조회하고, 실패하면 KCI로 보완해 DOI 또는 KCI 식별자를 확정.
- 핵심 단계
- Crossref 제목·저자·연도 조회.
- Crossref에서 확정하지 못하면 KCI 폴백 실행.
doi_confidence임계값 0.8 이상에서만 자동 적용하고, 미달 후보는 파일에 반영하지 않음.
5. citation-extractor¶
- 기능 — 본문 말미의 참고문헌 목록을 구조화된 항목으로 추출.
- 핵심 단계
- 참고문헌 섹션 경계 탐지.
- 개별 인용 항목 파싱(저자·연도·제목·출처 분해).
- 정규화된 인용 레코드 직렬화.
6. figure-table-extractor (v2.0)¶
- 기능 — 그림·표를 추출하고 본문 내 참조 링크와의 정합성을 보정.
- 핵심 단계
- 도표 객체와 캡션 영역 탐지.
- 본문 참조 표현과 도표 번호의 링크 정합성 검사 및 캡션 매칭.
- 정합된 도표·캡션 매핑 산출.
문서 처리 흐름¶
이 실행기의 계약은
produce+warn_and_flag이다. 변환 품질 0.7 미달은 수동 검토 대상으로 표시하고, DOI 신뢰도 0.8 미달 후보는 자동 적용하지 않는다.publish차단은 이 실행기의 분기가 아니라 7 · 교차 시스템 · Handoff Schema에 정의된 전역 품질 정책이다.
입력은 어디서 오는가 — 관련 논문 인제스트 체인¶
위 파이프라인은 PDF가 이미 손에 있다는 전제에서 시작한다. 그 PDF를 구해 오는 상위 글루가 별도로 있다. 매일 추천된 논문에 연구자가 "유용함"을 표시하면, 주간 잡이 그것을 받아 공개 접근(OA) 경로로 PDF를 확보하고 위 파이프라인에 밀어 넣은 뒤, 산출된 노트를 분석 역할(레이)로 넘긴다. 파이프라인 7개에 포함되지 않는 이유는 자체 처리를 하지 않고 기존 실행기들을 순서대로 호출하는 조립부이기 때문이다.
구조적 한계 — 자동화는 페이월에서 멈춘다. 2026-08-20 전수 실측에서 "유용함" 표시 48편 중 25편이 OA로 확보되지 않았다. 이 절반은 어떤 개선으로도 자동화되지 않는다. 기관 구독이나 상호대차로 사람이 PDF를 구해 지정 위치에 넣어야 하며, 체인은 그 지점에서 멈추는 대신 대기하도록 설계돼 있다. 확보되면 다음 실행이 이어받는다.
체인은 오래 끊겨 있었다 (2026-08-20 발견·복구)
이 체인은 구현돼 있었으나 양 끝이 조용히 끊긴 채로 돌고 있었다. 전수 감사 시점에 완전히 편입된 논문은 0편이었다. 원인은 두 갈래이며, 둘 다 예외를 던지지 않아 로그만 봐서는 정상으로 보였다.
- 입력 쪽 — 피드백 캐시가 최근 90일만 조회해 통째로 덮어쓰는 구조여서, 90일이 지난 표시가 사라졌다. 인제스터는 그 캐시만 읽었으므로 48편 중 30편이 시야 밖이었다. 원본 시트에는 전부 남아 있었다.
- 출력 쪽 — 변환기가
citekey필드를 발행하지 않았는데, 하류의 노트 조회와 핸드오프 발행은 둘 다 그 키로 노트를 찾았다. 변환된 노트는 구조적으로 분석 단계에 진입할 수 없었다.
복구는 append-only 원장 도입(입력)과 식별자 발행·조회 양단 정합(출력)으로 이뤄졌다. 여기서 얻은 일반 교훈은 백서의 다른 장에서도 반복된다 — 같은 대상을 부르는 이름이 단계마다 갈리면, 하류는 실패하지 않고 조용히 아무것도 하지 않는다.
재발 방지로 단계별 감사기를 두었다. "DB에 들어갔다"를 단일 플래그로 판정하지 않고 노트 없음 → 미시도 → 수급 대기 → 변환됨·미분석 → 근거 미검증 → 완료 6단계로 나눠 센다. 어느 칸에 쌓이는지가 어느 연결이 끊겼는지를 가리킨다.
리츠코 · Project Command — GitHub Hunter (1)¶
NERV 시스템에 도입할 외부 Claude Code 에이전트·스킬·플러그인을 GitHub에서 자율 탐색·필터링·평가하는 주간 7단계 오케스트레이터이다. 매주 일요일 자동 실행되며, fit-first 설계로 비용을 통제한다.
github-hunter¶
- 기능 — 외부 에이전트 후보를 자동 수집·필터·랭킹하고, 내부 fit 루브릭 점수가 가장 높은 1건을 자동 평가하여 보고.
- 핵심 단계 (7-stage)
- Wide harvest — 검색 쿼리·Awesome 리스트·토픽 기반 광역 후보 수집.
- Hard gate — 라이선스·최신성·안전성 등 자동 필터.
- Categorize — 후보를 A~D 카테고리로 분류.
- Fit 필터 — 카테고리 필터 + 히스토리 ledger 제외 + fit 점수 슬롯제 랭킹 = 1차 후보군.
- Evaluate — micro-eval 경량 사전 평가를 전건에 적용한 뒤, 적합도가 가장 높은 1건만 full-eval을 자동 수행.
- Index merge — 평가 결과를 인덱스에 병합.
- 보고 — Discord 채널에 3개 섹션(2차 후보군 / 다음 후보 / 컷) 요약 전달.
- 비용 통제 — full-eval은 매주 1건으로 제한(슬롯제). micro-eval은 후보당 경량 평가로 사전 스크리닝.
- 설치 정책 — 평가까지는 자동이지만, 실제 시스템 설치(도입)는 PI 승인 후에만 진행된다.
설계 메모¶
- 7개 파이프라인은 모두 LLM 서브에이전트가 아니라
scripts/실행 Python 오케스트레이터이다. 변환·API 조회·정합성 검사·랭킹처럼 재현성이 중요한 영역은 코드로 고정하고, 자연어 검토·보강·평가가 필요한 단계만 LLM에 맡기는 분리 원칙을 따릅니다. - 문서 처리 파이프라인은 입력→변환→검증→메타데이터→핸드오프의 단방향 흐름이며, 각 단계가 다음 단계의 입력 계약을 보장한다.
- GitHub Hunter는 "탐색·평가는 자동, 도입은 사람 승인"이라는 fit-first + human-in-the-loop 구조로, 자율성과 통제 사이의 균형을 의도한 설계이다.