Metadata-Version: 2.4
Name: thesis-review-agent
Version: 0.1.4
Summary: AI-assisted HWPX thesis citation and reference validation
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: openai-agents>=0.22.3
Requires-Dist: langgraph>=1.2.11
Requires-Dist: python-hwpx>=6.4.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0.0; extra == "dev"

# Thesis Review Agent

HWPX 논문에서 본문 인용과 참고문헌을 추출하고, AI 분류와 규칙 검증으로 표기 오류 후보를 반환하는 Python 패키지입니다. `result.document`에는 위반 원문을 `<highlight>...</highlight>` 태그로 표시한 `python-hwpx`의 `HwpxDocument` 객체가 담깁니다. 저장은 자동으로 하지 않으므로 필요하면 호출자가 원하는 경로에 직접 저장합니다.

현재 소스의 패키지 버전은 `0.1.3`입니다(`pyproject.toml` 기준).

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

## 설치 및 준비

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

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

이 저장소의 최신 변경을 사용하려면 저장소 루트에서 설치합니다.

```bash
python -m pip install -e .
```

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

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

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

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

## 바로 사용하기

아래 코드는 파일을 검토하고 분석 결과를 JSON으로 출력합니다. 검토된 HWPX 문서 객체는 Python에서 직접 다루거나, 선택적으로 호출자가 저장할 수 있습니다.

```python
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)
    # 필요할 때만 호출자가 검토 문서를 저장합니다.
    if result.document is not None:
        result.document.save_to_path("reviewed.hwpx")

    # 원본 파일 바이트를 제외하고 분석 결과를 출력합니다.
    payload = result.model_dump(mode="json", exclude={"source_hwpx_bytes"})
    print(json.dumps(payload, ensure_ascii=False, indent=2))


asyncio.run(main())
```

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

### 실행 모델 지정하기

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

```python
result = await agent.run(hwpx_bytes, model="gpt-6-luna")
```

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

### 진행 상황 스트리밍

`stream()`은 내부 그래프 상태를 노출하지 않고, 다음 세 종류의 Pydantic 이벤트를 순서대로 반환합니다. 각 이벤트는 `.event`, 타입이 지정된 `.data`, SSE 직렬화 메서드 `.to_sse()`를 제공합니다.

| SSE event | Python 타입 | `data` 내용 |
| --- | --- | --- |
| `progress` | `ProgressStreamEvent` | `node_name`, `message`, `unmatched_violation_count` (마지막 필드는 해당 시점에만 값이 있음) |
| `result` | `ResultStreamEvent` | 최종 `ThesisReviewResult`의 JSON 표현. `quotations`, `references`, `reference_scope_matches`, `quotation_issues`, `reference_issues` 포함 |
| `done` | `DoneStreamEvent` | 정상 완료를 나타내는 `finish_reason: "stop"` |

`result` 이벤트의 `data.document`는 Python 코드에서 `HwpxDocument`로 사용할 수 있지만 SSE JSON에는 직렬화하지 않습니다. 원본 HWPX 바이트도 결과 payload에서 제외됩니다. 스트림에서 예외가 발생하면 `stream()`은 예외를 호출자에게 전달하며, `error` SSE 이벤트로 바꾸지는 않습니다.

#### FastAPI 서버 예제

아래 예제는 요청 body로 받은 HWPX 바이트를 검토하고 각 타입 이벤트를 SSE 형식으로 반환하는 POST 엔드포인트입니다. FastAPI는 이 패키지의 필수 의존성이 아니므로 서버에 별도로 설치합니다.

```bash
python -m pip install fastapi uvicorn
```

```python
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse

from thesis_review_agent import ThesisReviewAgent

app = FastAPI()
review_agent = ThesisReviewAgent()


@app.post("/review/stream")
async def review_stream(request: Request) -> StreamingResponse:
    hwpx_bytes = await request.body()

    async def event_stream():
        async for event in review_agent.stream(hwpx_bytes):
            yield event.to_sse()

    return StreamingResponse(
        event_stream(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "X-Accel-Buffering": "no",
        },
    )
```

서버를 실행하고 HWPX 파일을 POST로 전송합니다. `-N`은 curl의 출력 버퍼링을 끕니다.

```bash
uvicorn app:app --reload
curl -N -X POST \
  -H "Content-Type: application/octet-stream" \
  --data-binary @thesis.hwpx \
  http://127.0.0.1:8000/review/stream
```

SSE wire 형식은 이벤트마다 `event:` 줄, JSON `data:` 줄, 빈 줄 순서입니다. 예를 들어 완료된 응답은 아래처럼 진행 이벤트가 여러 개 온 뒤 결과와 완료 이벤트로 끝납니다.

```text
event: progress
data: {"node_name":"sentence_classify_node","message":"문장과 소속 텍스트 조각을 분류 중입니다.","unmatched_violation_count":null}

event: result
data: {"quotations":[],"references":[],"reference_scope_matches":[],"quotation_issues":[],"reference_issues":[]}

event: done
data: {"finish_reason":"stop"}

```

프로그래밍 방식으로 사용하면 SSE 문자열 대신 타입이 유지된 이벤트 객체를 직접 받을 수 있습니다.

```python
async for event in review_agent.stream(hwpx_bytes, model="gpt-6-luna"):
    if event.event == "progress":
        print(event.data.message)
    elif event.event == "result":
        result = event.data  # ThesisReviewResult
        if result.document is not None:
            result.document.save_to_path("reviewed.hwpx")
    elif event.event == "done":
        print("검토 스트림 완료")
```

`EventSource`는 브라우저에서 GET 연결에 주로 쓰입니다. 위 업로드 예제는 POST이므로 브라우저에서 사용할 때는 `fetch()`의 응답 body를 읽어 SSE frame을 처리하거나, 업로드 후 GET 스트림을 여는 별도 API 구조를 사용하세요. `ProgressStreamEvent`, `ResultStreamEvent`, `DoneStreamEvent`와 `ReviewStreamEvent` 타입은 `thesis_review_agent`에서 가져올 수 있습니다.

## 결과 읽기

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

| 응답 필드 | 내용 |
| --- | --- |
| `source_hwpx_bytes` | 입력한 원본 파일 바이트. JSON에서는 Base64 문자열 |
| `document` | 위반 원문에 태그를 삽입한 `python-hwpx.HwpxDocument` 객체. Python 속성으로 제공되며 JSON에서는 제외 |
| `quotations` | 추출한 인용 원문·저자·연도·인용 분류 결과 |
| `references` | 참고문헌 원문·상위 자료유형·REF 및 유형별 세부 분류·추출 서식 |
| `quotation_issues` | CIT 규칙의 위반 후보 |
| `reference_issues` | REF·TYP 규칙의 위반 후보 |
| `reference_scope_matches` | 본문 인용과 참고문헌의 대응 결과: `matched`, `unmatched`, `undetermined` |

JSON 직렬화에는 `result.model_dump(mode="json")`을 사용합니다. 원본 HWPX 바이트도 기본적으로 포함됩니다. 위 사용 예시처럼 `exclude={"source_hwpx_bytes"}`로 제외하면 분석 결과만 직렬화됩니다. `HwpxDocument`는 JSON 결과에서 제외되며, 저장하려면 `result.document.save_to_path(path)` 또는 `result.document.to_bytes()`를 호출합니다.

### 위반 내용과 문서 위치

| 필드 | 의미 |
| --- | --- |
| `rule_id` | 위반 후보의 규칙 ID (`CIT-001`, `REF-021`, `TYP-009` 등) |
| `message` | 위반으로 판단한 이유와 수정 안내 |
| `quotation` | 위반된 본문 인용 문자열. 참고문헌 이슈에서는 `null` |
| `text` | 인용이 포함된 원문 문장 또는 참고문헌 항목 |
| `location` | 원문 위치. 구역·문단·run·content·문장 번호를 사용자용 1부터 시작하는 번호로 제공 |

`reference_scope_matches` 각 항목에는 대조 대상 종류(`reference` 또는 `quotation`), 원문, 비교 가능한 저자·연도, 상태, 대응 원문 목록, 설명, 문서 위치가 들어갑니다. 본문 인용과 참고문헌의 정규화된 첫 저자·연도가 유일하게 일치할 때 매칭합니다. 키가 없거나 중복되어 안전하게 대조할 수 없는 경우에는 AI를 호출하지 않고 `undetermined`로 남깁니다. 따라서 이 대조 단계는 별도의 AI 토큰을 사용하지 않습니다.

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

### highlight 태그가 반영된 문서 읽기

태그는 `result.document` 안의 `python-hwpx` 텍스트 run에 직접 들어갑니다. 문서 전체 평문은 `result.document.text.plain()`으로 확인할 수 있고, 검토된 HWPX는 다음처럼 저장해 한글 프로그램에서 열 수 있습니다.

```python
if result.document is not None:
    print(result.document.text.plain())
    # 선택적으로 HWPX 파일로 저장
    result.document.save_to_path("reviewed.hwpx")
```

예를 들어 다음과 같이 반환됩니다.

```text
본문 인용:
선행 연구 <highlight>(Kim 2020)</highlight>는 다음과 같다.

참고문헌:
<highlight>오동근. (2020). 도서명. 출판사.</highlight>
```

| 위반 종류·상황 | 표시 범위 |
| --- | --- |
| CIT 위반 | 지정된 문맥 안에서 찾은 인용 문자열 |
| 묶음 인용의 재구성된 괄호 문자열 | 괄호 전체가 원문에 없으면 해당 괄호 안 문자열 |
| 인용 문자열을 찾지 못했지만 위반 문맥은 확인됨 | 위반 문맥 전체 |
| REF·TYP 위반 | 위반 참고문헌 항목 전체. REF-002처럼 본문 위치를 가진 위반은 해당 본문 문맥 |
| 제목·주석 누락 등 목록 전체의 문제 | 검증기가 위치로 지정한 대표 항목 |
| 중복되거나 겹치는 위반 | 범위를 합쳐 한 번만 표시 |
| 여러 run·문장 조각에 걸친 항목 | 각 `sentence.text`의 해당 부분마다 태그를 열고 닫음 |
| 위치가 잘못됐거나 위반 원문을 유일하게 찾지 못함 | 태그를 삽입하지 않고 위반 목록은 유지 |

위치 매칭은 위반에 기록된 문서 위치와 해당 문단 원문을 사용합니다. 문서 전체에서 같은 문자열을 찾아 일괄 표시하지 않습니다. 현재 위반 모델에는 정확한 오류 글자 범위가 없으므로 참고문헌의 잘못된 쉼표나 단어 하나만 따로 강조하는 기능은 아닙니다. 찾지 못한 위반 개수는 표시 노드의 진행 이벤트 `unmatched_violation_count`에서 확인할 수 있습니다.

### 태그 삽입 후 원문과 서식 좌표

| 데이터 | 최종 반환 시 기준 |
| --- | --- |
| `result.document` | 태그를 텍스트에 삽입한 `python-hwpx.HwpxDocument` 객체 |
| `result.document` 저장 | 호출자가 `save_to_path()` 또는 `to_bytes()`를 명시적으로 호출 |
| 추출·분류 결과와 위반 목록의 원문·서식 | 검증 당시의 태그 없는 원문 기준 |
| `source_hwpx_bytes` | 입력한 원본 파일 그대로 |

표시 노드는 내부 분석 모델에서 위반 위치를 찾고, 보존해 둔 원본 run 인덱스를 통해 해당하는 `python-hwpx` 텍스트 run에 태그를 반영합니다. 태그는 실제 서식이 아니라 텍스트 문자열입니다. 라이브러리는 파일을 자동 저장하지 않으며, `result.document`는 호출자가 저장할 때 사용할 수 있습니다. [표시 노드 상세 안내](thesis_review_agent/graph/nodes/annotation/highlight_violations_node/README.md)에서 위치 매칭과 처리 범위를 확인할 수 있습니다.

## 검증 흐름

```text
HWPX 변환 → 문장 분류
  ├─ 본문 인용 추출·분류
  └─ 참고문헌 추출
       ├─ 자료유형 분류 → 유형별 TYP 검증
       └─ 일반 REF 규칙용 특성 분류
  본문 인용·참고문헌 대응 대조
  TYP 검증·REF 특성 분류·대응 대조 결과 → REF 검증 → CIT 검증
  → highlight_violations_node → 태그가 포함된 `HwpxDocument` 반환
```

분류가 필요한 적용 조건이나 자료 특성은 내부 AI 노드에서 판별하고, 해당 분류 결과를 바탕으로 검증 노드가 규칙을 적용합니다. 검증을 모두 마친 다음 표시 노드가 문서 모델의 텍스트를 변경합니다. 표시 노드와 REF-001·002용 대응 대조는 AI를 호출하지 않습니다. 노드별 내부 동작은 [그래프 실행 흐름](thesis_review_agent/graph/README.md), [유형별 TYP 실행 조건](thesis_review_agent/graph/nodes/validation/reference_type_validation_node/README.md), [표시 노드 상세 안내](thesis_review_agent/graph/nodes/annotation/highlight_violations_node/README.md)를 참고하세요.

참고문헌 자료유형 검증은 항목마다 상위 유형과 세부 유형 하나를 선택합니다. 도서·회의·학위논문의 세부 분류는 여러 `is_*` 유형 flag 대신 `material_kind` 하나로 반환합니다. 정기간행물의 독자적 DB도 `periodical_type=dedicated_content_database`로 표현합니다. 선택한 유형에 필요한 규칙들은 함께 적용합니다. 예를 들어 TV 에피소드는 저자 역할과 에피소드 형식을 함께 검사하지만 영화나 팟캐스트 형식은 검사하지 않습니다. [유형별 실행 조건](thesis_review_agent/graph/nodes/validation/reference_type_validation_node/README.md)에서 구체적인 경로를 확인할 수 있습니다.

## 테스트

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

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

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

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

## 제한 사항

- 지원 입력은 HWPX 바이트이며, DOCX/PDF 입력은 지원하지 않습니다. 수정 문서는 `result.document`로 반환하며 파일 저장은 호출자가 수행합니다.
- highlight 태그는 `python-hwpx` 문서 객체의 텍스트에 삽입되는 리터럴 문자열입니다. 모든 위반이 정확한 글자 단위로 표시되는 것은 아니며, 표시 여부와 무관하게 위반 목록을 함께 확인해야 합니다.
- 추출·분류가 잘못되거나 문서 서식 정보가 충분하지 않으면 위반을 놓치거나 오탐할 수 있습니다.
- 그래프 실행 중 발생한 예외는 호출자에게 전달됩니다.
