USAGE_GUIDE.md

ConversAI Usage Guide

Quick Start

1. Installation

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

export HUGGINGFACE_API_KEY="your_hf_token_here"
export LLM_PROVIDER="huggingface"

Option B: OpenAI

export OPENAI_API_KEY="your_openai_key_here"
export LLM_PROVIDER="openai"

Option C: Anthropic

export ANTHROPIC_API_KEY="your_anthropic_key_here"
export LLM_PROVIDER="anthropic"

Option D: Local LM Studio

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

3. Run the Application

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:

   [
     {"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

{
  "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

[
  {
    "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:

pip install -r requirements.txt --upgrade

API Usage (Advanced)

You can also use the modules programmatically:

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! 🔬