docs/development.md

# Development Guide

This guide captures what future contributors need to know to extend the AI Survey Simulator quickly.

## Environment Essentials

- Python 3.9+
- Ollama running locally (or another LLM provider wired into `llm_client.py`)
- Optional GPU for faster inference

```bash
cp .env.example .env                # adjust values as needed
pip install -r requirements.txt
```

Key environment variables (see `.env.example`):

- `LLM_BACKEND` — `ollama` (local default) or `openrouter`
- `LLM_HOST` / `LLM_MODEL` — target endpoint & model ID
- `LLM_API_KEY`, `LLM_SITE_URL`, `LLM_APP_NAME` — required when using OpenRouter
- `APP_PASSWORD` — optional shared password gate (when set, the UI + API require login)
- `FRONTEND_BACKEND_BASE_URL` and `FRONTEND_WEBSOCKET_URL` — how the UI talks to FastAPI
- `LOG_LEVEL` — INFO by default

## Running the Stack

### Recommended (HF-like) Local Run

This project is deployed on Hugging Face Spaces using Docker. The closest local workflow is to run the Docker image locally:

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

### One Command (legacy local stack)
```bash
./run_local.sh
```
- Starts `ollama serve` (if not already running) — this mode expects `LLM_BACKEND=ollama`
- Launches FastAPI backend and Gradio frontend in the background
- Press `Ctrl+C` to stop all three processes

### Manual Terminals (for logs, legacy)
```bash
# Terminal 1
ollama serve

# Terminal 2
cd backend
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# Terminal 3
cd frontend
python gradio_app.py
```

### Web UI (React hybrid)

The primary demo UI is served by `frontend/react_gradio_hybrid.py` and includes the analysis panel (bottom-up, care rubric, and top-down codebook categories).

When running outside Docker, you typically run the backend and the web UI separately; when running in Docker/HF, the backend is mounted under `/api` inside the same server.

The UI includes a **Configuration** view used to edit app-wide settings and personas stored in SQLite at `DB_PATH` (shared across users on HF). Persona selection for actually running conversations is done in the **AI-to-AI** and **Human-to-AI** panels.

## Making Changes Safely

- All configuration flows through `config/settings.py`; add new settings there and reference them via `get_settings()`.
- When adding LLM providers, implement a new client in `backend/core/llm_client.py` and hook it into the existing factory.
- Keep WebSocket message schemas stable (`backend/api/conversation_ws.py`); update both backend and frontend consumers if you change them.

## Testing & Verification

- No automated test suite yet. Add lightweight `pytest` modules under `tests/` as you extend functionality.
- Manually verify through the primary web UI (`frontend/react_gradio_hybrid.py`).
- For persistence + history: complete a run, confirm it appears in **History**, restart the container, and confirm it still appears and exports download.
- For persona config: edit the shared system prompt and/or a user persona in **Configuration**, click **Save**, and confirm the change is reflected in subsequent runs.
- If you need to debug the conversation loop, instrument `backend/core/conversation_manager.py` or launch a shell and run it directly.

## Notes on Persistence (HF)

Hugging Face Spaces provide a persistent volume (typically mounted at `/data` in Docker Spaces). This repo persists sealed runs (conversation finished + analysis succeeded) to SQLite at `DB_PATH` (recommended on HF: `/data/converta/converta.db`).

## Capabilities

See `docs/capabilities.md` for a concise description of what the app does today.

Note: the resource agent retries twice on transient OpenRouter errors (5s, 10s) before surfacing a failure in the UI.