llm-wiki-harness

# LLM Wiki Harness

도메인에 상관없이 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

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

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)

python -m src.ingest.run --sources "raw/*"

결과:

• wiki/*.md 페이지 생성/갱신
• wiki/index.md 갱신
• wiki/log.md 갱신

Step 4) Run Viewer (Screen Check)

python -m src.ui.app

UI에서 확인:

• 왼쪽: 페이지 목록/본문
• 오른쪽: 현재 페이지 스코프 기반 Q&A

4. MCP Tool List and Operation

MCP 서버 실행:

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)

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

codex.cmd mcp list
codex.cmd mcp get llm-wiki

Remove registration (optional)

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