Metadata-Version: 2.4
Name: ko-prompt-compressor
Version: 0.1.1
Summary: Korean prompt compressor with semantic preservation guard
License-Expression: MIT
Keywords: korean,prompt,compression,llm,nlp
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: Korean
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: kiwi
Requires-Dist: kiwipiepy>=0.18; extra == "kiwi"
Provides-Extra: llm
Requires-Dist: llama-cpp-python>=0.3; extra == "llm"
Requires-Dist: huggingface-hub>=0.20; extra == "llm"
Provides-Extra: verify
Requires-Dist: sentence-transformers>=3.0; extra == "verify"
Requires-Dist: torch>=2.0; extra == "verify"
Requires-Dist: huggingface-hub>=0.20; extra == "verify"
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn>=0.29; extra == "server"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Requires-Dist: httpx>=0.27; extra == "mcp"
Provides-Extra: all
Requires-Dist: ko-prompt-compressor[kiwi]; extra == "all"
Requires-Dist: ko-prompt-compressor[llm]; extra == "all"
Requires-Dist: ko-prompt-compressor[verify]; extra == "all"
Requires-Dist: ko-prompt-compressor[server]; extra == "all"

# ko-prompt-compressor

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

[![PyPI](https://img.shields.io/pypi/v/ko-prompt-compressor)](https://pypi.org/project/ko-prompt-compressor/)
[![Python](https://img.shields.io/pypi/pyversions/ko-prompt-compressor)](https://pypi.org/project/ko-prompt-compressor/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 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 / 설치

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

Optional extras:

```bash
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

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

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

### Python API

```python
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

```bash
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`):

```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]`) |
