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

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:

./run_docker_local.sh

One Command (legacy local stack)

./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)

# 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.