Metadata-Version: 2.4
Name: hallu-lab
Version: 0.1.0
Summary: 로컬 LLM(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
Requires-Dist: ollama>=0.3.0
Provides-Extra: notebook
Requires-Dist: jupyter; extra == "notebook"
Requires-Dist: pandas; extra == "notebook"

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

로컬 LLM(Ollama)을 사용해 다음 두 가지 현상을 직접 관찰하는 교육용 파이썬 패키지입니다.

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

---

## 1. 사전 준비

```bash
# (1) Ollama 설치  →  https://ollama.com/download
# (2) 가벼운 모델 내려받기 (3B 권장: 노트북에서도 무난)
ollama pull llama3.2

# (3) 이 패키지 설치 (code 디렉토리에서)
pip install -e .
#   주피터까지 함께:  pip install -e ".[notebook]"
```

설치 후 Ollama 서버가 떠 있는지 확인:

```python
from hallu_lab import OllamaClient
client = OllamaClient(model="llama3.2")
print(client.is_available())   # True 면 준비 완료
```

---

## 2. 빠른 사용 (주피터)

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

client = OllamaClient(model="llama3.2", 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=400))
```

자세한 단계별 실습은 [examples/demo.py](examples/demo.py) 를 참고하세요.

---

## 3. 패키지 구조

| 파일 | 역할 |
|------|------|
| [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`로 온도가 높을수록 답이 흔들리는 것을 관찰.
- **길이 효과**: `length_sweep`에서 `num_ctx`를 작게(예: 512) 주면 컨텍스트 창을 넘쳐 정보가 잘리는 현상을 더 극적으로 재현.
- **위치 효과**: `position_sweep`에서 보통 중앙(50%)에서 성공률이 가장 낮음.
