Metadata-Version: 2.4
Name: hallu-lab
Version: 0.2.0
Summary: 할루시네이션과 컨텍스트 정보 소실을 실습하는 교육용 패키지 (다운로드 없는 시뮬레이터 + Ollama 지원)
Author-email: uwpark <uwpark@simplatform.com>
Keywords: llm,hallucination,context,education,ollama
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: ollama
Requires-Dist: ollama>=0.3.0; extra == "ollama"
Provides-Extra: notebook
Requires-Dist: jupyter; extra == "notebook"
Requires-Dist: pandas; extra == "notebook"

# hallu_lab — LLM 할루시네이션 & 컨텍스트 소실 실습

LLM에서 나타나는 두 가지 현상을 직접 관찰하는 교육용 파이썬 패키지입니다.

1. **할루시네이션(환각)** — 모델이 모르는 것을 그럴듯하게 지어내는 현상
2. **컨텍스트 정보 소실** — 문맥이 길어지거나 핵심 정보가 가운데 묻히면 놓치는 현상

**두 가지 백엔드를 지원합니다.**

| 백엔드 | 다운로드 | 설명 |
|--------|----------|------|
| `sim` (기본) | **없음** | 현상을 규칙으로 재현하는 시뮬레이터. 오프라인·즉시 실행. 개념 학습용. |
| `ollama` | 모델 용량 | 실제 로컬 LLM. 더 현실적인 잡음 관찰 가능. |

---

## 1. 설치

```bash
pip install -e .          # code 디렉토리에서 (시뮬레이터는 외부 의존성 없음)
# 주피터까지:  pip install -e ".[notebook]"
```

> 시스템 파이썬이 외부 관리(PEP 668) 상태라 설치가 막히면 가상환경을 쓰세요:
> ```bash
> python3 -m virtualenv .venv && .venv/bin/pip install -e . ipykernel
> .venv/bin/python -m ipykernel install --user --name hallu-lab --display-name "Python (hallu-lab)"
> ```
> 주피터에서 커널을 **`Python (hallu-lab)`** 로 선택하면 됩니다.

---

## 2. 빠른 사용

```python
from hallu_lab import make_client, run_hallucination_demo, length_sweep, position_sweep, summarize

# 다운로드 없는 시뮬레이터 (기본)
client = make_client("sim", seed=0)

# 실습 A: 할루시네이션 — 가드레일 유무 비교
for r in run_hallucination_demo(client):
    r.show()

# 실습 B-1: 문서가 길어질수록 핵심 정보를 놓치는가 (길이 효과)
summarize(length_sweep(client, filler_sizes=[10, 100, 300, 600]))

# 실습 B-2: 핵심 정보 위치에 따른 차이 (lost-in-the-middle)
summarize(position_sweep(client, n_filler=120))
```

실제 로컬 LLM으로 바꾸려면 클라이언트 한 줄만 교체:

```python
client = make_client("ollama", model="qwen2.5:0.5b", seed=0)  # 약 400MB
# 사전: pip install "hallu-lab[ollama]"  +  `ollama serve`  +  `ollama pull qwen2.5:0.5b`
```

단계별 실습은 [examples/demo.ipynb](examples/demo.ipynb) 또는 [examples/demo.py](examples/demo.py) 참고.

---

## 3. 패키지 구조

| 파일 | 역할 |
|------|------|
| [hallu_lab/__init__.py](hallu_lab/__init__.py) | `make_client()` 팩토리 + 공개 API |
| [hallu_lab/simulated.py](hallu_lab/simulated.py) | 다운로드 없는 시뮬레이터 (`SimulatedClient`) |
| [hallu_lab/client.py](hallu_lab/client.py) | 실제 Ollama 호출 래퍼 (`OllamaClient`) |
| [hallu_lab/datasets.py](hallu_lab/datasets.py) | 허구 질문 / 바늘·채움 텍스트 생성 |
| [hallu_lab/hallucination.py](hallu_lab/hallucination.py) | 할루시네이션 실습 (`run_hallucination_demo`, `temperature_sweep`) |
| [hallu_lab/context_loss.py](hallu_lab/context_loss.py) | 컨텍스트 소실 실습 (`length_sweep`, `position_sweep`) |

---

## 4. 실습 포인트 (강의용)

- **가드레일 효과**: "모르면 모른다고 하라"는 시스템 프롬프트를 줬을 때 할루시네이션이 줄어드는지 비교.
- **온도(temperature)**: `temperature_sweep`로 온도 0은 동일, 높을수록 답이 흔들리는 것을 관찰.
- **길이 효과**: `length_sweep`에서 문서가 길어질수록 핵심 정보를 놓침. `num_ctx`를 작게(예: 512) 주면 창을 넘쳐 잘리는 현상을 더 극적으로 재현.
- **위치 효과**: `position_sweep`에서 보통 중앙(50%)에서 성공률이 가장 낮음 (lost-in-the-middle).

> ⚠️ 시뮬레이터(`sim`)는 진짜 신경망이 아니라 현상을 재현하는 규칙 기반 모형입니다.
> "정답"을 보는 게 아니라 실패 패턴/개념을 관찰하는 용도입니다.
