Survey Insight Assistant Prototype

This repo includes a small FastAPI prototype for chatting with survey data through a browser UI.

Start the prototype

Requirements:

• Python 3.13+
• uv

Install dependencies:

uv sync

Set the environment variables the prototype uses:

export OPENROUTER_API_KEY=...
export OPENAI_API_KEY=...
export TAVILY_API_KEY=...

Notes:

• OPENROUTER_API_KEY is used by the main chat agent. The default model is google/gemini-2.5-flash via OpenRouter.
• OPENAI_API_KEY is used for embeddings in the vector search tool.
• TAVILY_API_KEY is only needed if you want web search to work.

Make sure the processed survey assets exist under data/processed/. This repo already contains sample files for the Mental_Health_Tech survey:

• data/processed/Mental_Health_Tech_metadata.json
• data/processed/Mental_Health_Tech_segmentation_analysis.json
• data/processed/Mental_Health_Tech_vector_store.json

Run the app:

uv run python fast-api-chat/app/api/main.py

Then open:

http://localhost:8000

Or the terminal:

uv run main.py

How it works

• The FastAPI backend lives in fast-api-chat/app/api/main.py.
• The UI is a static chat page served from fast-api-chat/app/static/.
• On connect, the app loads survey metadata from data/processed/*_metadata.json and lists the available surveys in the chat.

If you want to add a new survey

Run the preprocessing pipeline to create the processed files:

uv run python insight_bot/preprocessing/run_preprocessing.py path/to/survey.csv

That will generate the metadata, segmentation analysis, and vector store files needed by the prototype.