Spaces:

jmisak
/

ProjectEcho

Sleeping

File size: 6,009 Bytes

d4abd8e

---

title: ConversAI - Qualitative Research Assistant
emoji: 🔬
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.45.0
app_file: app.py
pinned: false
license: mit
---


# ConversAI - AI-Powered Qualitative Research Assistant

Battle the blank page, reach global audiences, and uncover insights with AI assistance.

---

> **✨ NEW (Nov 2025):** Now uses **Microsoft Phi-3** - Faster, reliable, and **completely FREE** on HuggingFace!

---

## 🌟 Features

### 📝 Survey Generation
- Generate professional surveys from simple outlines
- Follow industry best practices automatically
- Choose from qualitative, quantitative, or mixed methods
- Customize number of questions and target audience

### 🌍 Survey Translation
- Translate surveys to 18+ languages
- Maintain cultural appropriateness and meaning
- Reach global audiences effortlessly
- Batch translation support

### 📊 Data Analysis
- AI-assisted thematic analysis
- Sentiment analysis and emotional insights
- Automatic pattern and trend detection
- Generate actionable insights and recommendations
- Export detailed analysis reports

## 🚀 Quick Start

**On HuggingFace Spaces:** Works immediately with zero configuration! Uses the free HF Inference API.

**Workflow:**
1. **Generate a Survey**: Start with an outline or topic description
2. **Translate**: Select target languages to reach global audiences
3. **Collect Responses**: Use the generated survey with your participants
4. **Analyze**: Upload responses to uncover key findings and trends

## 🔧 Configuration

### Default: HuggingFace Free Tier (Completely FREE!)

**✨ Zero configuration needed!** ConversAI works out-of-the-box on HuggingFace Spaces.

**Default Model:** Microsoft Phi-3-mini-4k-instruct
- ✅ **100% Free** - No API keys, no costs, ever
- ✅ **Fast** - Optimized for speed (10-30 seconds)
- ✅ **Ungated** - No approval needed, works immediately
- ✅ **Good Quality** - Suitable for professional survey work
- ✅ **Reliable** - Stable on HuggingFace Inference API

**Setup for PUBLIC Spaces (Recommended):**
- Just deploy - uses built-in `HF_TOKEN` automatically
- **No configuration required at all!**

**Setup for PRIVATE Spaces:**
1. Go to https://huggingface.co/settings/tokens
2. Copy your token (read permission is enough)
3. Add in Space Settings → Variables:
   - Name: `HUGGINGFACE_API_KEY`
   - Value: your_token_here
4. Restart Space

### Alternative Free Models

You can try different free models by setting the `LLM_MODEL` environment variable:

**Recommended Free Models:**

| Model | Best For | Speed | Quality | Ungated |
|-------|----------|-------|---------|---------|
| **microsoft/Phi-3-mini-4k-instruct** (default) | General use, balanced | ⚡⚡ Fast | ⭐⭐⭐ Good | ✅ Yes |
| **google/flan-t5-xxl** | Fast responses, instructions | ⚡⚡⚡ Very Fast | ⭐⭐ Decent | ✅ Yes |
| **mistralai/Mistral-7B-Instruct-v0.2** | Best quality (slower) | ⚡ Slower | ⭐⭐⭐⭐ Excellent | ✅ Yes |
| **google/flan-t5-xl** | Maximum speed | ⚡⚡⚡ Very Fast | ⭐⭐ Decent | ✅ Yes |
| **google/flan-ul2** | Long contexts | ⚡⚡ Fast | ⭐⭐⭐ Good | ✅ Yes |

**To change model:**
```bash

# In Space Settings → Variables

LLM_MODEL=mistralai/Mistral-7B-Instruct-v0.2

```

**Or in code:**
```python

import os

os.environ["LLM_MODEL"] = "google/flan-t5-xxl"

```

### Tips for Best Performance with Free Models

1. **Keep prompts concise** - Shorter outlines = faster generation
2. **Request fewer questions** - Start with 5-10 instead of 20+
3. **Translate one language at a time** - Better reliability on free tier
4. **Be patient on first request** - Models need to "warm up" (30-60 sec)
5. **Use during off-peak hours** - Less queue time, faster responses
6. **Try different models** - Some work better for specific tasks

## 📦 Installation

```bash

# Install dependencies

pip install -r requirements.txt



# Check environment setup (optional but recommended)

python check_env.py



# Run the app

python app.py

```

## 🏗️ Architecture

ConversAI is built with a modular architecture:

- **llm_backend.py** - Unified LLM interface supporting multiple providers

- **survey_generator.py** - AI-powered survey generation
- **survey_translator.py** - Multi-language translation engine

- **data_analyzer.py** - Qualitative data analysis and insights
- **app.py** - Gradio-based web interface
- **export_utils.py** - Export to JSON, CSV, Markdown



## 📄 Data Privacy



- All processing is done through your configured LLM provider

- No data is stored permanently by this application

- Survey data and responses remain in your control

- Suitable for sensitive research projects



## 🤝 Contributing



Contributions are welcome! This is a production-grade application designed for real-world qualitative research.



## 📝 License



MIT License - Feel free to use for research and commercial purposes.



---



## 📚 Documentation



**New to ConversAI?** Start with **[USER_GUIDE.md](USER_GUIDE.md)** for a complete walkthrough.



**Full Documentation Index:** See **[DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)** for all available guides.



**Quick Links:**

- 📖 [Complete User Guide](USER_GUIDE.md) - How to use ConversAI (START HERE)

- ⚡ [Quick Start for HF Spaces](QUICK_START_HF_SPACES.md) - 5-minute deployment

- 🔧 [Troubleshooting](TROUBLESHOOTING.md) - Common issues and solutions

- 🚀 [Deployment Guide](DEPLOYMENT.md) - Detailed deployment instructions

- 📋 [Usage Guide](USAGE_GUIDE.md) - Technical usage documentation

- 🆓 [Free Models Guide](FREE_MODELS.md) - Best free models to use



**Diagnostic Tools:**

- Run `python check_env.py` - Check your environment setup

- Run `python test_hf_backend.py` - Test HuggingFace connection



---



Built with ❤️ using Gradio and state-of-the-art open-source LLMs