README.md

---
title: Anti-Hallucination Chat
emoji: 💬
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
python_version: "3.12"
short_description: Grounded chat + on-demand claim audit
---

# Anti-Hallucination Chat

Freely chat with Flash-Lite (no tools), then press **Hallucination check** to
progressively rewrite the conversation into searched bullets and judge which
points look supported, uncertain, or contradicted.

## Local run

```bash
cp .env.example .env   # set GOOGLE_API_KEY
uv sync
uv run streamlit run app.py
```

On Cursor Cloud, if the preview looks stale after edits, restart Streamlit
(hard browser reload is not enough). See `.cursor/CURSOR_CLOUD_STREAMLIT.md`.

Optional env:

```bash
CHAT_MODEL=gemini-3.1-flash-lite       # main chat only
AUDIT_MODEL=gemini-3.5-flash-lite      # claim extract + judge + search planner
SEARCH_MODEL=gemma-4-26b-a4b-it        # web_search tool only (Google Search grounding)
CHAT_SYSTEM_PROMPT=You are a helpful assistant. Be accurate and clear.
AUDIT_USE_WEB_SEARCH=true              # fact-check assistant bullets online
AUDIT_WEB_SEARCH_PARALLEL=6            # concurrent per-bullet tool calls
```

## Workflow

1. Chat normally — the main reply **streams** token-by-token.
2. As soon as each reply finishes, a background auditor extracts bullets, then a
   **Gemma search agent** (with full conversation context) emits one enriched
   `web_search` tool call per bullet and runs those calls **in parallel**.
3. Click **Hallucination check** to **reveal** that audit stream (it does not
   start the audit — it only makes the already-running/finished stream visible).
4. Colors mean:
   - green = confirmed by search
   - orange = cannot prove or disprove
   - red = contradicted by search
   plus a report with sources.

## Hugging Face Spaces

This app ships as a **Docker Space** (Streamlit on port **7860**).
`GOOGLE_API_KEY` must be a Space **secret** (not committed).

### One-shot deploy

```bash
cd hallucination
export HF_TOKEN=hf_...                 # write token
export GOOGLE_API_KEY=...              # Gemini key → Space secret
# optional override:
# export SPACE_ID=another-user/another-space
# export SPACE_PRIVATE=1
bash scripts/deploy_hf_space.sh
```

The checked-in `.hf-space-id` points to the currently deployed personal Space:
[`MHRDYN7/sandbox-a049dee5`](https://huggingface.co/spaces/MHRDYN7/sandbox-a049dee5).
Re-running the command above updates that same Space. `SPACE_ID` takes precedence
when you intentionally want to deploy elsewhere.

The script will:

1. Read the target from `SPACE_ID`, then `.hf-space-id`, then the HF username fallback
2. Update the existing Space, or create a public Docker Space if it does not exist
3. Upload app files (excluding `.env`, tests, caches)
4. Set the `GOOGLE_API_KEY` secret on the Space

Current app: https://mhrdyn7-sandbox-a049dee5.hf.space

### Manual steps (equivalent)

```bash
uv export --no-hashes --no-dev -o requirements.txt
hf auth login   # or export HF_TOKEN=...
hf repos create YOUR_NS/anti-hallucination-chat --type space --space-sdk docker --public --exist-ok
hf upload YOUR_NS/anti-hallucination-chat . --type space \
  --exclude ".env" --exclude ".venv/**" --exclude ".cursor/**" --exclude "tests/**"
hf spaces secrets add YOUR_NS/anti-hallucination-chat --secrets GOOGLE_API_KEY=YOUR_KEY
```

### Notes

- New Gradio/Docker Spaces on free CPU may require [HF PRO](https://huggingface.co/pro).
- Optional public variables: `CHAT_MODEL`, `AUDIT_MODEL`, `SEARCH_MODEL`, `AUDIT_USE_WEB_SEARCH`.
- Rebuild after code changes by re-running the deploy script (or `hf upload ...`).

## Tests

```bash
uv run python -m pytest tests/ -q
```