Thesis Review Agent

HWPX 논문에서 본문 인용과 참고문헌을 추출하고, AI 분류와 규칙 검증으로 표기 오류 후보를 반환하는 Python 패키지입니다. 문서를 수정하지는 않습니다.

현재 패키지 버전은 0.1.0입니다.

검토 보조 도구이므로 결과를 원문 및 적용할 학술 작성 지침과 대조해 확인하세요. AI 분류나 자동 검증은 완전한 학술적 판단을 보장하지 않습니다.

설치 및 준비

• Python 3.12 이상
• OpenAI API 키
• 검토할 HWPX 파일

python -m pip install thesis-review-agent
export OPENAI_API_KEY="your-api-key"

Windows PowerShell에서는 API 키를 다음처럼 설정할 수 있습니다.

$env:OPENAI_API_KEY = "your-api-key"

실행 환경에서는 OPENAI_API_KEY가 필요합니다. 실제 AI 호출을 포함하는 통합 테스트는 기본 테스트 묶음에서는 건너뛰며, 실행하려면 RUN_AI_INTEGRATION_TESTS=1도 설정해야 합니다.

기본 모델은 gpt-5.6-luna입니다. AI 호출 시 문장과 참고문헌 등 문서 내용이 API로 전달되고 사용료가 발생할 수 있습니다. 민감한 문서를 처리하기 전 조직의 보안 정책과 API 사용 조건을 확인하세요.

바로 사용하기

아래 코드는 파일을 검토하고 CIT·REF·TYP 위반 후보를 JSON으로 출력합니다.

import asyncio
import json
from pathlib import Path

from thesis_review_agent import ThesisReviewAgent


async def main() -> None:
    hwpx_bytes = Path("thesis.hwpx").read_bytes()
    agent = ThesisReviewAgent()

    result = await agent.run(hwpx_bytes)
    print(json.dumps(result.model_dump(mode="json"), ensure_ascii=False, indent=2))


asyncio.run(main())

run()은 내부 그래프 State 대신 공개 응답 모델인 ThesisReviewResult를 반환합니다. quotation_issues에는 본문 인용 규칙(CIT) 위반 후보가, reference_issues에는 참고문헌 일반 규칙(REF)과 자료유형별 규칙(TYP) 위반 후보가 있습니다. 목록이 비어 있으면 해당 실행에서 위반 후보를 찾지 못했다는 뜻이지, 문서가 모든 기준을 충족한다고 보증하는 것은 아닙니다.

다른 모델 지정하기

실행별 model 인수로 사용할 모델을 지정할 수 있습니다.

result = await agent.run(hwpx_bytes, model="gpt-5.6-luna")

설정을 생략하면 패키지 기본 모델을 사용합니다.

진행 상황 스트리밍

stream()은 검토 중 생성되는 진행 메시지와 그래프 업데이트를 순서대로 반환합니다. 각 이벤트는 mode, data 튜플이며, mode는 custom 또는 updates입니다.

async for mode, data in agent.stream(hwpx_bytes, model="gpt-5.6-luna"):
    print(mode, data)

이 API를 사용하면 내부 _graph에 직접 접근할 필요가 없습니다.

결과 읽기

ThesisReviewResult는 그래프 State 자체를 반환하지 않고, 사용자가 결과를 확인하거나 후처리할 때 필요한 입력 원본과 분석 결과만 공개합니다. 공개 모델은 thesis_review_agent.results 패키지에 클래스별 파일로 분리되어 있고 모두 Pydantic BaseModel입니다.

• source_hwpx_bytes: 입력한 원본 파일 바이트. JSON 직렬화에서는 안전하게 Base64 문자열로 변환됩니다.
• document: HWPX 변환 구조(HwpxModel). 원문 텍스트와 문단·run·서식 구조를 확인할 수 있습니다.
• quotations: 추출된 인용과 저자·연도 정보, 인용 검증 분류 결과.
• references: 참고문헌 원문과 상위 자료유형, REF 분류 및 유형별 세부 분류, 추출된 글자 서식.
• quotation_issues, reference_issues: 각각 CIT와 REF·TYP 검증에서 발견한 위반 후보.
• reference_scope_matches: 본문 인용과 참고문헌의 대응 결과. matched, unmatched, undetermined를 포함하며 판단 불가를 억지로 위반 처리하지 않습니다. REF-001·002는 충분한 정보가 있는 unmatched에 대해서만 보고됩니다.

JSON 직렬화에는 result.model_dump(mode="json")을 사용합니다. 원본 HWPX 바이트가 JSON 안에 포함되므로 결과 JSON 크기가 커질 수 있습니다. 바이트가 필요 없으면 직렬화 시 exclude={"source_hwpx_bytes"}로 제외할 수 있습니다.

reference_scope_matches 각 항목에는 대조 대상 종류(reference 또는 quotation), 원문, 비교 가능한 저자·연도, 상태, 대응 원문 목록, 설명, 문서 위치가 들어갑니다. 규칙 기반 키가 모호한 경우 근거가 겹치는 후보 쌍만 AI가 추가 비교하며, 확신이 없으면 undetermined로 유지합니다.

result.has_issues는 두 이슈 목록 중 하나라도 비어 있지 않은지 나타냅니다. 규칙 ID는 인용 검증의 CIT, 일반 참고문헌 검증의 REF, 자료유형별 참고문헌 검증의 TYP로 구분됩니다.

검증 흐름

HWPX 변환 → 문장 분류
  ├─ 본문 인용 추출·분류
  └─ 참고문헌 추출
       ├─ 자료유형 분류 → 유형별 TYP 검증
       └─ 일반 REF 규칙용 특성 분류 → REF 검증
  참고문헌 검증 완료 → CIT 검증

분류가 필요한 적용 조건이나 자료 특성은 내부 AI 노드에서 판별하고, 해당 분류 결과를 바탕으로 검증 노드가 규칙을 적용합니다. 공개 API는 내부 State와 그래프 객체를 반환하지 않습니다. 노드별 내부 동작을 이해하려는 개발자는 thesis_review_agent/graph/README.md를 참고하세요.

테스트

개발 의존성을 설치한 뒤 기본 테스트를 실행합니다. 이 명령은 네트워크/API를 사용하지 않는 테스트를 실행하고 실제 AI 통합 테스트는 건너뜁니다.

python -m pip install -e '.[dev]'
python -m pytest

실제 HWPX 파일과 OpenAI API로 전체 그래프를 확인하려면 .env에 OPENAI_API_KEY를 설정하고 다음처럼 실행합니다. 기본 입력 파일은 프로젝트 루트의 para.hwpx이며, 다른 파일은 THESIS_REVIEW_HWPX로 지정할 수 있습니다.

RUN_AI_INTEGRATION_TESTS=1 python -m pytest -m integration -s

제한 사항

• 지원 입력은 HWPX 바이트이며, DOCX/PDF 입력이나 원본 문서 자동 수정은 제공하지 않습니다.
• 추출·분류가 잘못되거나 문서 서식 정보가 충분하지 않으면 위반을 놓치거나 오탐할 수 있습니다.
• 그래프 실행 중 발생한 예외는 호출자에게 전달됩니다.