# openenv-halluguard

**Train and evaluate LLMs to avoid hallucinations.**

```bash
pip install openenv-halluguard
```

## Quick Start (5 lines)

```python
from hallucination_guard_env import HallucinationEnv

env = HallucinationEnv()
obs = env.reset()
result = env.step(answer="your answer", confidence=0.8)
print(f"Reward: {result.reward}, Hallucinated: {result.is_hallucination}")
```

## What It Does

HallucinationGuard-Env is an OpenEnv RL environment that trains AI models to:
- Answer **only from verified context** — no fabrication
- **Cite real sources** — quote verification
- **Calibrate confidence** — don't be overconfident when wrong

## Evaluation Example

```python
from hallucination_guard_env import HallucinationEnv

def my_model(question, context):
    # Call your LLM API here
    # Return answer based ONLY on context
    return "answer from context"

env = HallucinationEnv()
obs = env.reset()
action = my_model(obs.question, obs.context)
result = env.step(answer=action, confidence=0.8)

print(f"Hallucinated: {result.is_hallucination}")
print(f"Reward: {result.reward}")
```

## HTTP API (HuggingFace Space)

For full deployment, use the HuggingFace Space:

```python
import requests

BASE = "https://samsankar-hallucination-guard-env.hf.space"

# Start episode
obs = requests.post(f"{BASE}/reset").json()

# Submit answer
result = requests.post(f"{BASE}/step",
                       json={"answer": "your answer"}).json()

# View leaderboard
lb = requests.get(f"{BASE}/leaderboard").json()
```

## Features

- **38 datasets** — SQuAD, HaluEval, TruthfulQA, HotpotQA, MedQA, and more
- **Research-grade grader** — ROUGE + BERTScore + NLI-DeBERTa
- **3 task difficulties** — Beginner → Intermediate → Advanced
- **8 hallucination types** — Fabricated facts, false citations, overconfident wrong, etc.

## Links

- **HuggingFace Space**: https://huggingface.co/spaces/SamSankar/hallucination-guard-env
- **Interactive Docs**: https://samsankar-hallucination-guard-env.hf.space/docs
- **Leaderboard**: https://samsankar-hallucination-guard-env.hf.space/leaderboard

## License

MIT
