ko-prompt-compressor 0.1.5

Korean prompt compressor with semantic preservation guard

ko-prompt-compressor

Korean prompt compressor with semantic preservation guard.
한국어 프롬프트를 의미 손실 없이 압축해 LLM 토큰 비용을 줄입니다.

---

Features / 특징

• LLM compression — gemma-4-E2B Q4 기반, 30–50% reduction, 78% guard pass rate
  gemma4에 최적화 개발 — 압축 프롬프트·가드 임계값 모두 gemma4 튜닝
• Rule + morpheme fallback — works without LLM via kiwipiepy
  LLM 없이도 동작 (규칙 + kiwipiepy 형태소)
• Semantic guard — embedding similarity + critical_guard hard-veto
  임베딩 유사도 + critical_guard로 의미 손실 차단
• MCP server — plug-in to Claude Desktop / Claude Code
  Claude Desktop · Code에 MCP 툴로 연결

---

Install / 설치

pip install ko-prompt-compressor
ko-compress-setup          # 환경 감지 → 모델 선택 및 다운로드

Optional extras:

pip install "ko-prompt-compressor[kiwi]"    # 형태소 fallback (kiwipiepy)
pip install "ko-prompt-compressor[verify]"  # 의미 보존 검증 (sentence-transformers)
pip install "ko-prompt-compressor[server]"  # FastAPI 사이드카
pip install "ko-prompt-compressor[mcp]"     # MCP 서버 (Claude Desktop용)
pip install "ko-prompt-compressor[all]"     # 전부

---

Usage / 사용법

CLI

ko-compress "회의 참석 부탁드립니다. 감사합니다."
# → 회의 참석 부탁.
# [OK|llm/gemma4] 12→5 tok (58.3% saved)

ko-compress "텍스트" --json        # JSON 출력
ko-compress "텍스트" --ratio 0.5   # 목표 50% 유지

Python API

from ko_prompt_compressor import compress

result = compress("Redis로 분산 락 구현하려는데, TTL 만료 후 남의 락을 실수로 푸는 문제 어떻게 해결해")
print(result.text)    # Redis 분산 락. TTL 만료 후 타인 락 잘못 해제 해결법?
print(result.method)  # llm/gemma4
print(result.success) # True

FastAPI server

ko-compress-server          # http://127.0.0.1:57832

# POST /compress
curl -X POST http://127.0.0.1:57832/compress \
  -H "Content-Type: application/json" \
  -d '{"text": "원문 프롬프트", "ratio": 0.5}'

---

Claude Desktop / MCP 연동

~/.claude/claude_desktop_config.json (또는 claude_desktop_config.json):

{
  "mcpServers": {
    "ko-compress": {
      "command": "ko-compress-mcp"
    }
  }
}

등록 후 Claude Desktop 재시작. 이후 Claude에게 "이 프롬프트 압축해줘"라고 하면 compress_prompt 툴이 자동 호출됩니다.

Claude Code hook (자동 압축)

모든 프롬프트를 자동 압축하려면 ~/.claude/hooks/ko-compress-hook.py를 설치하세요.
ko-compress-setup이 hook 설치 옵션을 안내합니다.

---

Model / 모델

gemma-4-E2B Q4 (기본값, ~3.5 GB, RAM 8 GB+)

ko-prompt-compressor는 gemma4에 최적화되어 개발되었습니다. 압축 프롬프트(ko-rules-v3-en)와 critical_guard 임계값 모두 gemma4 기준으로 튜닝되어 있으며, 다른 모델에서는 동작을 보장하지 않습니다.

GPU(CUDA/Apple Silicon) 감지 시 자동 가속 적용.

모델 라이선스: gemma-4-E2B 및 unsloth 양자화 버전 모두 Apache 2.0. 별도 계정/동의 불필요.

---

Compression Pipeline / 압축 파이프라인

입력
 └→ LLM 압축 (GGUF + ko-rules-v3-en 프롬프트)
     └→ critical_guard veto 검사
         ├→ [통과] 출력
         └→ [실패] fallback: rules + kiwi 형태소
             └→ passthrough (압축 불가 시 원문 반환)

---

Requirements / 요구사항

• Python 3.10+
• llama-cpp-python — LLM 압축 (CPU pre-built wheel 지원)
• kiwipiepy — fallback 형태소 압축 (선택)
• sentence-transformers + torch — 의미 보존 검증 (선택)

---

License

MIT

Third-party licenses

Dependency	License	Notes
gemma-4-E2B (Google / unsloth)	Apache 2.0	기본 LLM 모델
kiwipiepy	LGPL v3	선택적 의존성 ([kiwi]), 동적 링크 사용
sentence-transformers	Apache 2.0	선택적 의존성 ([verify])