# LLM Wiki Harness

![demo](./demo/demo.png)

도메인에 상관없이 `raw/`의 자료를 읽어 `wiki/` 지식베이스를 구축/조회하는 하네스입니다.  
처음 사용하는 사람도 30분 내에 첫 위키 문서를 만들고 UI에서 확인할 수 있도록 구성되어 있습니다.

## 1. Assignment Checklist Mapping
이 저장소는 `assignment.md` 기준으로 다음 항목을 제공합니다.

- `HARNESS`
  - 운영 지침: `AGENTS.md`
  - 추가 컨텍스트/스킬: `SKILL.md` (raw 읽기 전용 규칙 포함)
- `LLM Wiki`
  - `raw/`, `wiki/` 스키마
- `Visualization tools`
  - MCP 서버: `src/mcp_server/main.py`
  - 뷰어(UI): `src/ui/app.py`
- `README.md`
  - 설치/실행, MCP 툴, 데이터 입력, 검증 절차 포함
- `demo/`
  - `demo/demo.png` (렌더링 증빙)

## 2. Repository Structure
```text
raw/               # 원본 지식 소스(읽기 전용)
wiki/              # 생성/갱신되는 위키 페이지
src/ingest/        # ingest 파이프라인
src/mcp_server/    # MCP 서버 및 도구
src/ui/            # PyQt 위키 뷰어 + Q&A
AGENTS.md          # 위키 에이전트 운영 규칙
SKILL.md           # 실행 스킬(특히 raw read-only)
```

## 3. 30-Minute Quickstart (First-Timer)
### Step 0) Prerequisites
- Python 3.11+ (Windows 기준) (Python 3.13에서 실행 확인 완료)
- Codex CLI 설치 및 PATH 등록 (`codex` 또는 `codex.cmd`)

### Step 1) Environment Setup
```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

의존성(`requirements.txt`):
- `fastmcp`
- `PyQt6`
- `pytest` (선택적)

### Step 2) Put Your Own Data
1. `raw/` 폴더에 소스 파일을 넣습니다. (예: `.md`, `.txt`, `.pdf`)
2. 주의: `raw/`는 원본 보존 영역입니다. 수정/삭제 대신 파일 추가를 권장합니다.

### Step 3) Ingest (Create First Wiki Article)
```powershell
python -m src.ingest.run --sources "raw/*"
```

결과:
- `wiki/*.md` 페이지 생성/갱신
- `wiki/index.md` 갱신
- `wiki/log.md` 갱신

### Step 4) Run Viewer (Screen Check)
```powershell
python -m src.ui.app
```

UI에서 확인:
- 왼쪽: 페이지 목록/본문
- 오른쪽: 현재 페이지 스코프 기반 Q&A

## 4. MCP Tool List and Operation
MCP 서버 실행:
```powershell
python -m src.mcp_server.main
```

제공 도구:
- `ingest_sources(source_patterns="*")`
  - `raw/`의 파일 패턴을 ingest
- `list_pages()`
  - 위키 페이지 목록/메타데이터 조회
- `get_page(page_id)`
  - 단일 페이지 본문/메타 조회
- `query_wiki(question, page_scope=None)`
  - 페이지 스코프 기반 질의응답
- `lint_wiki()`
  - 링크/기본 무결성 점검

## 4-1. Register MCP Server in Codex CLI
Codex CLI에 이 프로젝트의 MCP 서버를 등록하면, Codex 세션에서 바로 도구를 호출할 수 있습니다.

### Windows (PowerShell)
```powershell
codex mcp add llm-wiki --env PYTHONPATH=%프로젝트 경로% --env PYTHONUTF8=1 --env PYTHONIOENCODING=utf-8 -- %프로젝트 경로%\.venv\Scripts\python.exe -m src.mcp_server.main
```
### Verify registration
```powershell
codex.cmd mcp list
codex.cmd mcp get llm-wiki
```

### Remove registration (optional)
```powershell
codex.cmd mcp remove llm-wiki
```

## 5. Data Input / Integration Request Method
### A. CLI 기반 입력
- 파일 추가: `raw/`에 소스 투입
- 통합 요청: ingest 명령 실행

### B. Agent/MCP 기반 요청
- 자연어로 "`raw/*` ingest 해줘" 요청
- MCP 호출 시 `ingest_sources`에 패턴 전달

권장 패턴:
- 전체: `raw/*`
- 특정 유형: `raw/*.md`, `raw/*.pdf`
- 특정 파일: `raw/my-source.md`

## 6. Verification Method (What to Check)
아래 4가지를 만족하면 정상입니다.

1. 파일 생성 확인
- `wiki/index.md`, `wiki/log.md`, 신규 `wiki/*.md` 존재

2. 인덱스 반영 확인
- `wiki/index.md`에 새 페이지 링크 추가

3. 로그 반영 확인
- `wiki/log.md`에 ingest/query/lint 이력 추가

4. 화면 검증
- `python -m src.ui.app` 실행 후 페이지 렌더링/Q&A 응답 확인

## 7. Optional Environment Variables
- `CODEX_BIN`: Codex CLI 실행 파일명
- `CODEX_MODEL`: 사용할 모델
- `CODEX_TIMEOUT_SECONDS`: Codex 응답 타임아웃(기본 300)

## 8. Troubleshooting
- `Codex CLI binary not found`
  - Codex CLI 설치 또는 `CODEX_BIN` 환경변수 설정
- UI에서 페이지가 비어 있음
  - ingest 먼저 실행 후 UI 재시작
- ingest 결과가 없음
  - `raw/`에 파일이 실제로 있는지, 패턴이 맞는지 확인

## 9. Demo Evidence
- 스크린샷: `demo/demo.png`