---
title: ConverTA
emoji: 💻
colorFrom: indigo
colorTo: gray
sdk: docker
pinned: false
---

# AI Survey Simulator – Quick Start

The folllowing are the instructions for running the simulator either with a local Ollama model or with a hosted OpenRouter model.

---

## Requirements

- Python 3.9+
- Pip
- Optional for local mode: [Ollama](https://ollama.ai) with a pulled model (e.g., `ollama pull llama3.2:latest`)
- Optional for hosted mode: OpenRouter account + API key

---

## 1. Create `.env`

Copy `.env.example` to `.env` and choose one of the following blocks.

**Local (Ollama)**
```
LLM_BACKEND=ollama
LLM_HOST=http://localhost:11434
LLM_MODEL=llama3.2:latest
```

**Hosted (OpenRouter)**
```
LLM_BACKEND=openrouter
LLM_HOST=https://openrouter.ai/api/v1
LLM_MODEL=anthropic/claude-3-haiku:beta   # pick any model
LLM_API_KEY=sk-or-...
LLM_SITE_URL=http://localhost:7860
LLM_APP_NAME=AI_Survey_Simulator
```

Other environment values (ports, websocket URL, log level) are already set in `.env.example`.

---

## 2. Install Python Dependencies

```
python -m venv .venv          # optional
source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

---

## 3. Run the Stack

### Option A – HF-like (recommended)

```bash
./run_docker_local.sh
```

This runs the same Dockerized web UI used on Hugging Face Spaces.

### Option B – Single Command (legacy local stack)
```
./run_local.sh
```
Reads `.env`, starts Ollama if needed, launches FastAPI + Gradio, and keeps them running until `Ctrl+C`.

### Option C – Manual Terminals (legacy)
1. *(Only if LLM_BACKEND=ollama)* `ollama serve`
2. `cd backend && uvicorn api.main:app --host 0.0.0.0 --port 8000`
3. `cd frontend && python gradio_app.py`

Backend listens on `http://localhost:8000`, Gradio on `http://localhost:7860`.

---

## 4. Use the App

1. Open the UI URL.
2. If `APP_PASSWORD` is set, enter it on the login page to unlock the app.
3. (Optional) Open **Configuration** to choose personas and add per-role prompt additions.
4. Click **Start Conversation**.
5. Wait for the conversation to complete to see analysis results.
   - Note: **Stop Conversation** currently aborts the run and may skip post-conversation analysis.

After the conversation completes, the app runs post-conversation analysis and populates:
- Bottom-up findings (emergent themes) with evidence
- Top-down coding (care experience rubric + codebook categories) with evidence

### Human Chat (Human ↔ Surveyor)

- Open the **Human Chat** tab, click **Start**, then type as the patient.
- Click **End session** to run the same post-conversation analysis + enable exports.
- Click **Abort** to stop immediately (may skip analysis).

---

## 5. Personas

- Surveyor definitions: `data/surveyor_personas.yaml`
- Patient definitions: `data/patient_personas.yaml`

Edit the YAML, then restart the backend to apply changes.

---

## 6. Troubleshooting

| Issue | Resolution |
| --- | --- |
| “Temporary failure in name resolution” (OpenRouter) | Launch backend from an environment that can resolve `openrouter.ai`; ensure proxies/DNS settings match the working terminal. |
| “All connection attempts failed” | Backend cannot reach the LLM. Verify `.env`, restart backend, check console logs. |
| “Model not found” (Ollama) | Pull the model with `ollama pull <model>` and restart backend. |
| UI stays empty | Backend not running or `.env` mismatch. Restart both processes. |

---

## 7. Reference Docs

- `docs/overview.md` – architecture summary
- `docs/development.md` – environment tips and backend switching
- `docs/roadmap.md` – upcoming work