USAGE_GUIDE.md

# ConversAI Usage Guide

## Quick Start

### 1. Installation

```bash

# Clone or download the repository

cd ConversAI



# Install dependencies

pip install -r requirements.txt

```

### 2. Configuration

ConversAI supports multiple LLM providers. Choose one and configure:

#### Option A: HuggingFace (Recommended for HF Spaces)
```bash

export HUGGINGFACE_API_KEY="your_hf_token_here"

export LLM_PROVIDER="huggingface"

```

#### Option B: OpenAI
```bash

export OPENAI_API_KEY="your_openai_key_here"

export LLM_PROVIDER="openai"

```

#### Option C: Anthropic
```bash

export ANTHROPIC_API_KEY="your_anthropic_key_here"

export LLM_PROVIDER="anthropic"

```

#### Option D: Local LM Studio
```bash

export LLM_PROVIDER="lm_studio"

export LM_STUDIO_URL="http://localhost:1234/v1/chat/completions"

```

### 3. Run the Application

```bash

python app.py

```

The app will be available at `http://localhost:7860`

## Features Guide

### 📝 Survey Generation

Generate professional surveys from simple outlines.

**Steps:**
1. Navigate to the "Generate Survey" tab
2. Enter your research outline or topic description
   - Example: "I want to understand patient experiences with a new diabetes medication"
3. Select survey type: Qualitative, Quantitative, or Mixed
4. Set number of questions (5-25 recommended)
5. Specify your target audience
6. Click "Generate Survey"

**Best Practices:**
- Be specific about your research goals
- Mention key topics you want to explore
- Include context about your target respondents
- Start with 10-15 questions for most surveys

**Output:**
- Formatted survey preview
- Downloadable JSON file with full survey data
- Questions follow industry best practices
- Includes introduction and closing messages

### 🌍 Survey Translation

Translate your surveys to reach global audiences.

**Steps:**
1. Generate a survey first (or have one ready)
2. Navigate to the "Translate Survey" tab
3. Select target language(s) from the checkbox list
4. Click "Translate Survey"

**Supported Languages:**
- Spanish, French, German, Portuguese
- Chinese, Japanese, Korean
- Arabic, Hindi, Russian
- And 8+ more languages

**Features:**
- Maintains cultural appropriateness
- Preserves question intent and meaning
- Handles multiple languages in one batch
- Exports all translations in a single file

**Tips:**
- Translate to multiple similar languages to compare phrasing
- Use back-translation to verify accuracy
- Consider cultural context for sensitive topics

### 📊 Data Analysis

Uncover insights from your survey responses.

**Steps:**
1. Navigate to the "Analyze Data" tab
2. Prepare your responses in JSON format:
   ```json

   [

     {"q1": "response 1", "q2": "response 2"},

     {"q1": "response 1", "q2": "response 2"}

   ]

   ```
3. Optionally include questions for context
4. Click "Load Example" to see format
5. Click "Analyze Data"

**Analysis Includes:**
- **Executive Summary** - High-level overview
- **Themes** - Main topics identified in responses
- **Sentiment Analysis** - Emotional tone and distribution
- **Key Insights** - Actionable findings
- **Statistics** - Response metrics

**Output Formats:**
- Markdown report (for viewing)
- JSON file (for further processing)
- Both include complete analysis results

**Pro Tips:**
- Minimum 10-20 responses for meaningful analysis
- Include diverse perspectives for richer insights
- Provide questions for better context
- Export results for presentations

## File Formats

### Survey JSON Format
```json

{

  "title": "Survey Title",

  "introduction": "Welcome message",

  "questions": [

    {

      "id": 1,

      "question_text": "Your question here?",

      "question_type": "open_ended",

      "required": true,

      "help_text": "Optional clarification"

    }

  ],

  "closing": "Thank you message"

}

```

### Responses JSON Format
```json

[

  {

    "q1": "First question response",

    "q2": "Second question response",

    "q3": "Third question response"

  },

  {

    "q1": "Another respondent's answer",

    "q2": "Their second answer",

    "q3": "Their third answer"

  }

]

```

## Deployment to HuggingFace Spaces

1. Create a new Space on HuggingFace
2. Upload all `.py` files and `requirements.txt`
3. Upload `README.md` with the frontmatter
4. Set environment variables in Space settings:
   - Add `HF_TOKEN` (automatically available)
   - Or add API keys for other providers
5. Space will auto-deploy!

## Troubleshooting

### Issue: "LLM generation failed"
**Solutions:**
- Check your API key is set correctly
- Verify you have credits/quota with your provider
- Try a different provider
- Check network connectivity

### Issue: "Translation failed"
**Solutions:**
- Ensure survey was generated first
- Check API key and quota
- Try translating to fewer languages at once
- Verify the survey data is valid

### Issue: "Analysis returned no results"
**Solutions:**
- Check JSON format is valid
- Ensure responses is a list/array
- Provide at least 3-5 responses
- Check LLM provider is working

### Issue: "Module import errors"
**Solutions:**
```bash

pip install -r requirements.txt --upgrade

```

## API Usage (Advanced)

You can also use the modules programmatically:

```python

from llm_backend import LLMBackend, LLMProvider

from survey_generator import SurveyGenerator



# Initialize

backend = LLMBackend(provider=LLMProvider.OPENAI)

generator = SurveyGenerator(backend)



# Generate survey

survey = generator.generate_survey(

    outline="Study user satisfaction with mobile apps",

    survey_type="qualitative",

    num_questions=10,

    target_audience="Mobile app users aged 18-35"

)



print(survey)

```

## Best Practices

### For Survey Generation:
- Start with clear research objectives
- Be specific about your target audience
- Review and refine generated questions
- Test with a small pilot group first

### For Translation:
- Verify translations with native speakers
- Consider regional language variations
- Test cultural appropriateness
- Use back-translation for validation

### For Analysis:
- Collect sufficient responses (20+ ideal)
- Ensure response quality
- Combine with quantitative data when possible
- Review AI insights critically

## Support

For issues, questions, or contributions:
- Check the README.md
- Review this usage guide
- Open an issue on GitHub
- Contact the development team

## Tips for Production Use

1. **Data Privacy**: Review your LLM provider's data policy
2. **API Costs**: Monitor usage to control costs
3. **Rate Limits**: Be aware of provider rate limits
4. **Validation**: Always review AI-generated content
5. **Backup**: Save generated surveys and analyses
6. **Version Control**: Track survey versions
7. **Ethics**: Ensure informed consent from participants

---

Happy researching! 🔬