Upload 8 files

CHANGELOG.md

@@ -2,6 +2,79 @@
 
 All notable changes to ConversAI will be documented in this file.
 
+## [2.0.0] - 2025-10-26
+
+### Added - MAJOR FEATURE: Conversational Research
+- **💬 New Conversational Research Module**: AI-moderated interviews with dynamic adaptation
+  - **Design custom conversation flows** with scripted questions
+  - **AI moderator** conducts real-time interviews with intelligent probing
+  - **Dynamic follow-up questions** generated based on respondent answers
+  - **Intelligent probing logic**: Asks follow-ups when detecting interesting keywords or every N responses
+  - **Automatic summarization** of conversation insights
+  - **Export capabilities**: Transcripts, JSON, and CSV formats
+
+### New Files
+- **conversation_flow.py** - Conversation flow design and management
+  - `ConversationNode` class for individual conversation steps
+  - `ConversationFlow` class for managing complete flows
+  - Flow validation and persistence (save/load JSON)
+  - Example flow generator for quick start
+
+- **conversation_session.py** - Live conversation session tracking
+  - `ConversationTurn` class for tracking individual messages
+  - `ConversationSession` class for managing live interviews
+  - `SessionManager` for handling multiple concurrent sessions
+  - Conversation transcript generation
+  - Session statistics and analytics
+
+- **conversation_moderator.py** - AI-powered interview moderator
+  - Conducts interviews following conversation flows
+  - Decides when to ask scripted questions vs. dynamic follow-ups
+  - Generates contextual follow-up questions using LLM
+  - Probes on interesting keywords (emotional/reasoning indicators)
+  - Configurable follow-up threshold (default: every 3rd response)
+  - Conversation summarization capability
+
+### UI Enhancements
+- **New Tab: "💬 Conversational Research"** with two sub-interfaces:
+  - **🎨 Design Flow**: Create and manage conversation flows
+    - Create new flows or load example templates
+    - Add conversation nodes (questions, branches, endings)
+    - Live flow preview
+    - Save flows to JSON files
+
+  - **🎙️ Conduct Interview**: Chat-based interview interface
+    - Start conversation sessions from designed flows
+    - Real-time chat with AI moderator
+    - Session status tracking
+    - Export conversations in multiple formats
+
+### Export Utilities Enhanced
+- Added `conversation_to_transcript()` - Export as readable text
+- Added `conversation_to_json()` - Export session data as JSON
+- Added `conversation_to_csv()` - Export conversation turns as CSV
+- Added `flow_to_markdown()` - Document conversation flows
+
+### Technical Details
+- Seamless integration with existing Phi-2 LLM backend
+- Session state management with unique IDs
+- Timestamp tracking for all conversation turns
+- Node-based conversation flow with linked questions
+- Probing logic triggers on:
+  - Response length (>5 words)
+  - Turn count (every 3rd user response)
+  - Interesting keywords (emotional/reasoning words)
+
+### Use Cases
+- Qualitative research interviews
+- Customer feedback sessions
+- User experience research
+- Market research interviews
+- Product discovery conversations
+- Exploratory research with adaptive questioning
+
+---
+
 ## [1.2.0] - 2025-11-XX
 
 ### Changed - MAJOR UPDATE

README.md

@@ -1,171 +1,189 @@
----
-title: Project Echo - Qualitative Research Assistant
-emoji: 🔬
-colorFrom: blue
-colorTo: purple
-sdk: gradio
-sdk_version: 5.49.1
-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.
-
----
-
-> **✨ UPDATED (Nov 2025):** Now uses **local transformers** with **Microsoft Phi-2** - Fast, contextual, and **completely FREE**! No API dependencies, runs directly on HuggingFace Spaces. Generates actual topic-specific questions (not generic templates).
-
----
-
-## 🌟 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: Local Transformers (Completely FREE!)
-
-**✨ Zero configuration needed!** ConversAI works out-of-the-box on HuggingFace Spaces using local model loading.
-
-**Default Model:** microsoft/phi-2
-- ✅ **100% Free** - No API keys, no costs, ever
-- ✅ **Excellent quality** - 2.7GB causal language model, great at creative text generation
-- ✅ **Good speed** - Typically 5-10 seconds per request after initial load
-- ✅ **No API dependencies** - Runs entirely on your Space's compute
-- ✅ **Private** - All processing happens locally, nothing sent to external APIs
-- ✅ **Contextual** - Generates relevant, topic-specific questions (not generic)
-
-**Setup for HuggingFace Spaces:**
-- Just deploy - models download automatically on first run
-- **No API keys or tokens required!**
-- Models are cached after first download for faster subsequent loads
-
-### Alternative Free Models
-
-You can try different free models by setting the `LLM_MODEL` environment variable:
-
-**Recommended Free Models (Local Transformers):**
-
-| Model | Best For | Speed | Quality | Model Size |
-|-------|----------|-------|---------|------------|
-| **TinyLlama/TinyLlama-1.1B-Chat-v1.0** | Quick testing | ⚡⚡⚡ Very Fast | ⭐⭐ Fair | 1.1GB |
-| **google/gemma-2b-it** | Faster alternative | ⚡⚡ Fast | ⭐⭐⭐ Good | 2GB |
-| **microsoft/phi-2** (default) | **Recommended** - best balance | ⚡ Good | ⭐⭐⭐⭐ Excellent | 2.7GB |
-| **mistralai/Mistral-7B-Instruct-v0.2** | Maximum quality | ⚡ Slower | ⭐⭐⭐⭐⭐ Best | 7GB |
-
-**Note:** These are causal language models (decoder-only) designed for text generation. **Do NOT use Flan-T5 models** - they copy examples instead of generating contextual questions.
-
-**To change model:**
-```bash
-# In Space Settings → Variables
-LLM_MODEL=google/gemma-2b-it  # Faster alternative
-
-# Or for maximum quality (requires more memory)
-LLM_MODEL=mistralai/Mistral-7B-Instruct-v0.2
-```
-
-**Why Local Transformers?**
-- ✅ **No API dependencies** - runs entirely on your Space
-- ✅ **No 404 errors** - no network issues
-- ✅ **Fast after loading** - models cached in memory
-- ✅ **Instruction-tuned** - designed for following prompts
-- ✅ **Privacy** - all processing happens locally
-
-### Tips for Best Performance with Local Models
-
-1. **Use Phi-2 (default)** - Best balance of quality and resource usage
-2. **First load takes time** - Model downloads and loads (~2-3 minutes for Phi-2)
-3. **Subsequent requests are fast** - Model stays in memory (5-10 seconds)
-4. **For maximum quality** - Use Mistral-7B-Instruct (requires 8GB+ RAM)
-5. **For faster loading** - Use Gemma-2B-IT or TinyLlama (good quality, smaller)
-6. **Avoid Flan-T5 models** - They copy examples instead of generating contextual questions
-7. **Be specific in outlines** - More detail helps model generate better questions
-
-## 📦 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.
-
-**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
-- 🆓 [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
+---
+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.
+
+---
+
+> **✨ UPDATED (Nov 2025):** Now uses **local transformers** with **Microsoft Phi-2** - Fast, contextual, and **completely FREE**! No API dependencies, runs directly on HuggingFace Spaces. Generates actual topic-specific questions (not generic templates).
+
+---
+
+## 🌟 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
+
+### 💬 Conversational Research
+- Design custom conversation flows with scripted questions
+- AI-moderated interviews with dynamic follow-up questions
+- Real-time adaptation based on respondent answers
+- Intelligent probing for deeper insights
+- Automatic conversation summarization and export
+- Export conversations as transcripts, JSON, or CSV
+
+## 🚀 Quick Start
+
+**On HuggingFace Spaces:** Works immediately with zero configuration! Uses the free HF Inference API.
+
+**Workflow:**
+
+**Static Surveys:**
+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
+
+**Conversational Research:**
+1. **Design Flow**: Create a conversation flow with scripted questions
+2. **Conduct Interview**: AI moderator engages with respondents in real-time
+3. **Export & Analyze**: Export transcripts and analyze conversation insights
+
+## 🔧 Configuration
+
+### Default: Local Transformers (Completely FREE!)
+
+**✨ Zero configuration needed!** ConversAI works out-of-the-box on HuggingFace Spaces using local model loading.
+
+**Default Model:** microsoft/phi-2
+- ✅ **100% Free** - No API keys, no costs, ever
+- ✅ **Excellent quality** - 2.7GB causal language model, great at creative text generation
+- ✅ **Good speed** - Typically 5-10 seconds per request after initial load
+- ✅ **No API dependencies** - Runs entirely on your Space's compute
+- ✅ **Private** - All processing happens locally, nothing sent to external APIs
+- ✅ **Contextual** - Generates relevant, topic-specific questions (not generic)
+
+**Setup for HuggingFace Spaces:**
+- Just deploy - models download automatically on first run
+- **No API keys or tokens required!**
+- Models are cached after first download for faster subsequent loads
+
+### Alternative Free Models
+
+You can try different free models by setting the `LLM_MODEL` environment variable:
+
+**Recommended Free Models (Local Transformers):**
+
+| Model | Best For | Speed | Quality | Model Size |
+|-------|----------|-------|---------|------------|
+| **TinyLlama/TinyLlama-1.1B-Chat-v1.0** | Quick testing | ⚡⚡⚡ Very Fast | ⭐⭐ Fair | 1.1GB |
+| **google/gemma-2b-it** | Faster alternative | ⚡⚡ Fast | ⭐⭐⭐ Good | 2GB |
+| **microsoft/phi-2** (default) | **Recommended** - best balance | ⚡ Good | ⭐⭐⭐⭐ Excellent | 2.7GB |
+| **mistralai/Mistral-7B-Instruct-v0.2** | Maximum quality | ⚡ Slower | ⭐⭐⭐⭐⭐ Best | 7GB |
+
+**Note:** These are causal language models (decoder-only) designed for text generation. **Do NOT use Flan-T5 models** - they copy examples instead of generating contextual questions.
+
+**To change model:**
+```bash
+# In Space Settings → Variables
+LLM_MODEL=google/gemma-2b-it  # Faster alternative
+
+# Or for maximum quality (requires more memory)
+LLM_MODEL=mistralai/Mistral-7B-Instruct-v0.2
+```
+
+**Why Local Transformers?**
+- ✅ **No API dependencies** - runs entirely on your Space
+- ✅ **No 404 errors** - no network issues
+- ✅ **Fast after loading** - models cached in memory
+- ✅ **Instruction-tuned** - designed for following prompts
+- ✅ **Privacy** - all processing happens locally
+
+### Tips for Best Performance with Local Models
+
+1. **Use Phi-2 (default)** - Best balance of quality and resource usage
+2. **First load takes time** - Model downloads and loads (~2-3 minutes for Phi-2)
+3. **Subsequent requests are fast** - Model stays in memory (5-10 seconds)
+4. **For maximum quality** - Use Mistral-7B-Instruct (requires 8GB+ RAM)
+5. **For faster loading** - Use Gemma-2B-IT or TinyLlama (good quality, smaller)
+6. **Avoid Flan-T5 models** - They copy examples instead of generating contextual questions
+7. **Be specific in outlines** - More detail helps model generate better questions
+
+## 📦 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
+- **conversation_flow.py** - Conversation flow design and management
+- **conversation_session.py** - Live conversation session tracking
+- **conversation_moderator.py** - AI-powered interview moderator
+- **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.
+
+**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
+- 🆓 [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

USER_GUIDE.md

@@ -0,0 +1,1339 @@
+# ConversAI User Guide
+
+## Your AI-Powered Qualitative Research Assistant
+
+ConversAI is a professional-grade research platform that transforms how you create surveys, reach global audiences, and analyze qualitative data. Powered by advanced AI, it automates hours of manual work while maintaining the quality and rigor expected in professional research.
+
+---
+
+## 🎯 What ConversAI Does
+
+ConversAI provides three powerful capabilities that work together to streamline your entire research workflow:
+
+### 1. 📝 Generate Professional Surveys in Minutes
+Turn a simple outline into a complete, research-ready survey with industry best practices automatically applied.
+
+**What you get:**
+- Well-structured questions that avoid common biases
+- Professional introduction and closing messages
+- Appropriate question types for your research goals
+- Ready-to-deploy surveys that save hours of manual work
+
+**Perfect for:**
+- Market researchers launching new studies
+- UX researchers gathering user feedback
+- Academic researchers designing questionnaires
+- Product teams validating ideas
+- Healthcare professionals conducting patient surveys
+
+### 2. 🌍 Translate Surveys to Reach Global Audiences
+Instantly translate your surveys into 18+ languages while maintaining cultural appropriateness and meaning.
+
+**What you get:**
+- Professionally translated surveys in minutes
+- Cultural adaptation, not just word-for-word translation
+- Support for major world languages
+- Batch translation to multiple languages at once
+
+**Perfect for:**
+- International market research
+- Multi-country product launches
+- Global user studies
+- Diverse demographic research
+- Multilingual community surveys
+
+### 3. 📊 Uncover Insights from Qualitative Data
+Transform open-ended responses into actionable insights with AI-assisted analysis.
+
+**What you get:**
+- Thematic analysis identifying key patterns
+- Sentiment analysis and emotional insights
+- Executive summaries highlighting findings
+- Trend detection across responses
+- Exportable reports ready for presentations
+
+**Perfect for:**
+- Analyzing customer feedback
+- Understanding user pain points
+- Identifying product opportunities
+- Reporting research findings
+- Making data-driven decisions
+
+---
+
+## 💼 Why ConversAI is Production-Grade
+
+### Enterprise-Quality Features
+
+**1. Flexible LLM Backend**
+- Support for multiple AI providers (OpenAI, Anthropic, HuggingFace)
+- Automatic failover and provider selection
+- No vendor lock-in - switch providers anytime
+- Works with both free and premium AI services
+
+**2. Robust Error Handling**
+- Graceful degradation when services are unavailable
+- Clear, actionable error messages
+- Automatic retry logic for transient failures
+- Validation at every step to prevent bad data
+
+**3. Data Privacy & Security**
+- No permanent data storage by default
+- All processing through your chosen AI provider
+- Complete control over your research data
+- Suitable for sensitive research projects
+- Environment-based credential management
+
+**4. Professional Export Options**
+- JSON format for programmatic access
+- Markdown reports for documentation
+- CSV export for spreadsheet analysis
+- Ready for integration with other tools
+
+**5. Scalability**
+- Handle small pilot studies or large-scale research
+- Batch operations for efficiency
+- Optimized for performance
+- Rate limiting and cost controls
+
+**6. Production-Ready Architecture**
+- Modular, maintainable codebase
+- Clean separation of concerns
+- Comprehensive error handling
+- Extensive documentation
+- Easy deployment options
+
+### Quality Assurance
+
+**Research Best Practices:**
+- Questions designed to minimize bias
+- Appropriate question types for different data needs
+- Logical survey flow from general to specific
+- Culturally sensitive translations
+- Rigorous analytical methods
+
+**Technical Excellence:**
+- Comprehensive input validation
+- Type checking and error prevention
+- Graceful handling of edge cases
+- Performance optimization
+- Security-first design
+
+**User Experience:**
+- Intuitive interface requiring no technical knowledge
+- Clear status messages and progress indicators
+- Helpful examples and templates
+- Responsive design for any device
+- Accessibility considerations
+
+---
+
+## 🚀 How to Use ConversAI
+
+### Getting Started
+
+**Step 1: Access ConversAI**
+- On HuggingFace Spaces: Open the Space URL (works immediately)
+- Self-hosted: Launch with `python app.py`
+
+**Step 2: Verify Setup**
+- Look for the green status banner at the top
+- Should show: "✅ Active LLM Provider: [Provider Name]"
+- If you see a warning, check the About tab for setup instructions
+
+**Step 3: Choose Your Task**
+- Navigate between tabs based on what you want to do
+- Start with survey generation, then translate, then analyze
+
+---
+
+## 📝 Feature Guide: Survey Generation
+
+### Creating Your First Survey
+
+**1. Navigate to the "Generate Survey" Tab**
+
+**2. Describe Your Research**
+
+Enter your outline in the text box. Be specific about:
+- **Topic**: What are you researching?
+- **Goals**: What do you want to learn?
+- **Focus Areas**: What specific aspects matter?
+
+**Example Outlines:**
+
+```
+Good: "I want to understand patient experiences with a new
+diabetes medication, focusing on effectiveness in managing
+blood sugar, side effects experienced, and impact on daily
+quality of life."
+
+Better: "We're studying user satisfaction with our mobile
+banking app. Key areas: ease of use for common transactions,
+trust in security features, pain points in the account setup
+process, and feature requests for future versions."
+```
+
+**3. Configure Survey Settings**
+
+- **Survey Type**:
+  - *Qualitative*: Open-ended questions for deep insights
+  - *Quantitative*: Structured questions with measurable responses
+  - *Mixed*: Combination of both
+
+- **Number of Questions**:
+  - Start with 10-15 for most studies
+  - 5-8 for quick feedback surveys
+  - 15-25 for comprehensive research
+
+- **Target Audience**:
+  - Be specific: "Adults 25-45 who use fitness apps daily"
+  - Not just: "General public"
+
+**4. Generate and Review**
+
+Click "🚀 Generate Survey" and wait 10-30 seconds.
+
+Review the generated survey:
+- ✅ Questions are clear and unbiased
+- ✅ Appropriate question types are used
+- ✅ Logical flow from general to specific
+- ✅ Professional introduction and closing
+
+**5. Download and Deploy**
+
+- Download the JSON file for your survey platform
+- Copy questions to your preferred survey tool
+- Customize further if needed
+
+### Tips for Better Surveys
+
+**Do:**
+- ✅ Be specific about your research goals
+- ✅ Mention your target audience characteristics
+- ✅ Specify key topics or themes to explore
+- ✅ Include context about why you're researching
+
+**Don't:**
+- ❌ Use vague descriptions like "customer feedback"
+- ❌ Request too many questions (causes fatigue)
+- ❌ Skip the target audience field
+- ❌ Forget to review before deploying
+
+**Example Use Cases:**
+
+1. **Product Feedback**
+   ```
+   Outline: "Gather feedback from beta users of our project
+   management software. Focus on: workflow improvements over
+   previous tools, collaboration features effectiveness,
+   learning curve challenges, and missing features that would
+   increase productivity."
+   ```
+
+2. **Customer Experience**
+   ```
+   Outline: "Understand customer experience at our retail
+   stores. Key areas: staff helpfulness, product selection
+   satisfaction, checkout process efficiency, store
+   cleanliness, and likelihood to recommend."
+   ```
+
+3. **Academic Research**
+   ```
+   Outline: "Study remote work impact on work-life balance
+   among knowledge workers. Topics: boundary management,
+   productivity changes, social isolation, communication
+   challenges, and preferences for future work arrangements."
+   ```
+
+---
+
+## 🌍 Feature Guide: Survey Translation
+
+### Translating Surveys to Multiple Languages
+
+**1. Generate or Upload a Survey**
+- Create a survey using the generation feature, OR
+- Have your existing survey in the correct JSON format
+
+**2. Navigate to "Translate Survey" Tab**
+
+**3. Select Target Languages**
+
+Choose from 18+ supported languages:
+- **European**: Spanish, French, German, Italian, Portuguese, Dutch, Swedish, Polish
+- **Asian**: Chinese, Japanese, Korean, Vietnamese, Thai, Indonesian, Hindi
+- **Middle Eastern**: Arabic, Turkish
+- **Eastern European**: Russian
+
+**Pro Tip**: Select multiple languages at once for batch translation
+
+**4. Generate Translations**
+
+Click "🌐 Translate Survey" and wait.
+
+Processing time:
+- 1-2 languages: 20-40 seconds
+- 3-5 languages: 1-2 minutes
+- 6+ languages: 2-3 minutes
+
+**5. Review and Download**
+
+- Each translation appears in a separate section
+- Check for cultural appropriateness
+- Download JSON file containing all translations
+
+### Translation Best Practices
+
+**Quality Assurance:**
+
+1. **Back-Translation Testing**
+   - For critical surveys, have a native speaker back-translate
+   - Compare with original to ensure meaning preserved
+
+2. **Cultural Adaptation**
+   - Review idioms and expressions
+   - Check that examples make sense in target culture
+   - Verify formality level is appropriate
+
+3. **Pilot Testing**
+   - Test with small group of native speakers
+   - Gather feedback on clarity and appropriateness
+   - Refine before full deployment
+
+**When to Use Each Language:**
+
+| Language | When to Use | Notes |
+|----------|------------|-------|
+| Spanish | Latin America, Spain | Specify region for dialect |
+| French | France, Canada, Africa | Consider regional variations |
+| German | DACH region | Formal vs informal matters |
+| Chinese | China, Taiwan, Singapore | Simplified vs Traditional |
+| Arabic | MENA region | Right-to-left formatting needed |
+| Portuguese | Brazil, Portugal | Brazilian vs European Portuguese |
+
+### Use Cases
+
+1. **Global Product Launch**
+   ```
+   Scenario: Launching mobile app in 5 countries
+   Languages: English, Spanish, French, German, Japanese
+   Questions: 12 (mix of usability and satisfaction)
+   Time saved: ~8 hours of professional translation
+   ```
+
+2. **Multinational Employee Survey**
+   ```
+   Scenario: Annual engagement survey across offices
+   Languages: English, Chinese, Hindi, Spanish, Portuguese
+   Questions: 15 (engagement, culture, development)
+   Time saved: ~10 hours + faster deployment
+   ```
+
+3. **Academic International Study**
+   ```
+   Scenario: Cross-cultural research project
+   Languages: English, French, German, Italian, Spanish
+   Questions: 20 (detailed qualitative questions)
+   Time saved: Professional translation would cost $500+
+   ```
+
+---
+
+## 📊 Feature Guide: Data Analysis
+
+### Analyzing Survey Responses
+
+**1. Prepare Your Data**
+
+Format responses as JSON array:
+
+```json
+[
+  {
+    "q1": "First respondent's answer to question 1",
+    "q2": "First respondent's answer to question 2",
+    "q3": "First respondent's answer to question 3"
+  },
+  {
+    "q1": "Second respondent's answer to question 1",
+    "q2": "Second respondent's answer to question 2",
+    "q3": "Second respondent's answer to question 3"
+  }
+]
+```
+
+**2. Navigate to "Analyze Data" Tab**
+
+**3. Input Your Data**
+
+- Paste responses JSON in the "Survey Responses" field
+- Optionally add questions JSON for better context
+- Use "Load Example" button to see format
+
+**4. Run Analysis**
+
+Click "🔍 Analyze Data" and wait 30-60 seconds.
+
+**5. Review Results**
+
+The analysis includes:
+
+**Executive Summary**
+- High-level overview of findings
+- Key patterns observed
+- Notable discoveries
+- Response quality assessment
+
+**Thematic Analysis**
+- 5-7 main themes identified
+- Description of each theme
+- Prevalence percentages
+- Representative quotes
+
+**Sentiment Analysis**
+- Overall sentiment (positive/negative/neutral/mixed)
+- Sentiment distribution breakdown
+- Key emotions detected
+- Intensity assessment
+
+**Key Insights**
+- 5-7 actionable insights
+- Specific, evidence-based findings
+- Strategic recommendations
+- Trend observations
+
+**Statistics**
+- Total responses analyzed
+- Average response length
+- Completion rates
+- Data quality metrics
+
+**6. Download Reports**
+
+- JSON file: Full analysis data for further processing
+- Markdown file: Formatted report for presentations
+
+### Analysis Best Practices
+
+**Data Preparation:**
+
+1. **Minimum Response Count**
+   - Absolute minimum: 10 responses
+   - Good results: 20-50 responses
+   - Best results: 50+ responses
+
+2. **Response Quality**
+   - Encourage detailed, thoughtful responses
+   - Filter out spam or very short responses
+   - Include diverse perspectives
+
+3. **Data Cleaning**
+   - Remove duplicates
+   - Handle incomplete responses
+   - Fix formatting issues
+
+**Interpretation Guidelines:**
+
+1. **Themes**
+   - Look for recurring patterns
+   - Consider theme prevalence percentages
+   - Read example quotes for context
+   - Cross-reference with your research questions
+
+2. **Sentiment**
+   - Don't over-interpret mixed sentiment
+   - Look for sentiment patterns by theme
+   - Consider intensity levels
+   - Watch for contradictions
+
+3. **Insights**
+   - Prioritize insights supported by multiple responses
+   - Look for unexpected findings
+   - Consider business/research implications
+   - Validate with quantitative data when available
+
+**Common Pitfalls to Avoid:**
+
+❌ **Cherry-picking**: Don't just highlight what confirms your hypothesis
+✅ **Balanced reporting**: Include contradictory findings
+
+❌ **Small sample bias**: Don't generalize from <20 responses
+✅ **Appropriate scope**: Acknowledge sample size limitations
+
+❌ **Over-reliance on AI**: AI assists but doesn't replace human judgment
+✅ **Critical review**: Validate AI findings with domain expertise
+
+❌ **Ignoring context**: Raw numbers without situational understanding
+✅ **Contextual analysis**: Consider external factors and timing
+
+### Use Cases
+
+**1. Customer Feedback Analysis**
+```
+Input: 50 responses to "What could we improve?"
+Output:
+- 5 themes (pricing concerns, feature requests, UX issues, etc.)
+- Overall negative sentiment (68%) but constructive tone
+- 7 actionable insights for product roadmap
+Time saved: 4-6 hours of manual coding
+```
+
+**2. Employee Engagement Study**
+```
+Input: 120 responses across 10 open-ended questions
+Output:
+- Themes: work-life balance, career development, management
+- Mixed sentiment with strong positives and negatives
+- Insights on retention risks and opportunities
+Time saved: 8-12 hours of analysis
+```
+
+**3. User Research Interviews**
+```
+Input: 25 interview transcripts (formatted as responses)
+Output:
+- Themes: user goals, pain points, feature priorities
+- Positive sentiment on core functionality
+- Insights for next sprint planning
+Time saved: 6-8 hours of manual synthesis
+```
+
+---
+
+## 💬 Feature Guide: Conversational Research
+
+### Conducting AI-Moderated Interviews
+
+**What is Conversational Research?**
+
+Unlike static surveys, conversational research creates a dynamic dialogue between an AI moderator and respondents. The AI follows a scripted conversation flow but adapts in real-time by asking follow-up questions based on responses, creating a more natural and engaging interview experience.
+
+**When to Use Conversational Research:**
+- 🎤 Exploratory research where you want to probe deeper
+- 💡 User research requiring contextual follow-ups
+- 🔍 Customer discovery with adaptive questioning
+- 📝 Qualitative interviews at scale
+- 🤝 Situations requiring empathetic, human-like interaction
+
+### Designing a Conversation Flow
+
+**1. Navigate to "💬 Conversational Research" Tab**
+
+Click on the "🎨 Design Flow" sub-tab.
+
+**2. Create a New Flow**
+
+Enter flow details:
+- **Flow Name**: Descriptive title (e.g., "Product Feedback Interview")
+- **Flow Description**: Purpose and context of the conversation
+
+Click "✨ Create New Flow" to start.
+
+**3. Add Conversation Steps**
+
+For each question/step:
+- **Question/Message**: The scripted question the AI will ask
+- **Step Type**: Choose "Question" or "End"
+  - *Question*: Regular conversation step
+  - *End*: Final closing message
+
+Click "➕ Add Step" to add each node to the flow.
+
+**Example Flow Structure:**
+```
+Step 1 (Question): "Hello! Thank you for taking the time to speak with me.
+                    What initially attracted you to our product?"
+
+Step 2 (Question): "How would you describe your overall experience using
+                    the product so far?"
+
+Step 3 (Question): "What specific features do you find most valuable?"
+
+Step 4 (Question): "Have you encountered any challenges or frustrations?"
+
+Step 5 (Question): "What improvements would you most like to see?"
+
+Step 6 (End): "Thank you for sharing your thoughts! Your feedback is
+               incredibly valuable."
+```
+
+**4. Preview Your Flow**
+
+The flow preview shows:
+- All conversation steps in order
+- Step types and IDs
+- How the conversation will progress
+
+**5. Save Your Flow**
+
+Click "💾 Save Flow" to save to a JSON file.
+
+**Pro Tip**: Start by clicking "📋 Load Example" to see a complete customer feedback interview template.
+
+### Conducting an Interview
+
+**1. Navigate to "🎙️ Conduct Interview" Sub-Tab**
+
+**2. Start a Conversation Session**
+
+Click "🚀 Start Conversation" to begin.
+
+The AI moderator will:
+- Greet the respondent
+- Ask the first question from your flow
+- Wait for a response
+
+**3. Respond as the Interviewee**
+
+Type your response in the text box and click "Send" (or press Enter).
+
+**4. Experience Dynamic Adaptation**
+
+The AI moderator intelligently decides whether to:
+
+**Ask Scripted Question** (Default):
+- Continues with the next question in your flow
+- Maintains structure and coverage
+
+**Ask Dynamic Follow-Up** (Adaptive):
+- Probes deeper into interesting responses
+- Generated based on what you just said
+- Examples: "Tell me more about...", "Can you elaborate on...", "Why do you think..."
+
+**Triggers for Follow-Up Questions:**
+- Every 3rd user response (configurable)
+- Responses longer than 5 words
+- Interesting keywords detected:
+  - Emotional: "frustrated", "excited", "worried", "confused"
+  - Reasoning: "because", "however", "although", "surprisingly"
+
+**5. Session Progress**
+
+Monitor session status:
+- Active conversation indicator
+- Turn count
+- Current flow position
+
+**6. Export the Conversation**
+
+When finished, click "📥 Export Conversation" to save:
+- **Transcript**: Readable text format (.txt)
+- **JSON**: Full session data with timestamps
+- **CSV**: Turn-by-turn analysis format
+
+### Best Practices for Conversation Flows
+
+**Flow Design:**
+
+1. **Start Broad, Get Specific**
+   ```
+   Good flow:
+   1. General experience → 2. Specific features → 3. Pain points → 4. Improvements
+
+   Poor flow:
+   1. Very specific detail → 2. General opinion (order reversed)
+   ```
+
+2. **Optimal Flow Length**
+   - Short interviews: 4-6 questions
+   - Standard interviews: 6-10 questions
+   - In-depth interviews: 10-15 questions
+   - Note: AI follow-ups extend the conversation naturally
+
+3. **Question Types**
+   - Open-ended: "Tell me about...", "Describe your experience..."
+   - Focused: "What specific features...", "When did you first..."
+   - Reflective: "How did that make you feel?", "What did you learn?"
+
+4. **Professional Tone**
+   - Empathetic and non-judgmental
+   - Clear and conversational
+   - Respectful of respondent's time
+   - Genuine curiosity
+
+**Conducting Interviews:**
+
+1. **Set Expectations**
+   - Tell respondents this is an AI-moderated interview
+   - Mention it will ask follow-up questions
+   - Encourage detailed responses (5+ words)
+
+2. **Response Quality**
+   - Encourage thoughtful, detailed answers
+   - Very short responses (<5 words) won't trigger follow-ups
+   - Rich responses get more adaptive probing
+
+3. **Managing Length**
+   - AI limits follow-ups to avoid fatigue
+   - Flow continues even with dynamic questions
+   - Respondents can keep answers brief to move faster
+
+4. **Technical Tips**
+   - One respondent per session
+   - Sessions auto-save conversation history
+   - Can't resume abandoned sessions (by design)
+   - Export immediately after completion
+
+### Use Cases
+
+**1. Customer Discovery Interviews**
+```
+Scenario: Understanding why users chose your product
+Flow: 5 scripted questions about decision process
+AI Adaptation: Probes on "competitor comparison" mentions
+Result: Rich insights on differentiation factors
+Time: 15-20 minutes per interview
+```
+
+**2. UX Research Sessions**
+```
+Scenario: Exploring pain points in onboarding flow
+Flow: 8 questions walking through user journey
+AI Adaptation: Asks follow-ups on confusion/frustration
+Result: Detailed understanding of UX issues
+Time: 20-25 minutes per session
+```
+
+**3. Product Feedback at Scale**
+```
+Scenario: Collecting beta feedback from 50 users
+Flow: 6 standard questions + AI follow-ups
+AI Adaptation: Probes interesting feature requests
+Result: Prioritized roadmap from user insights
+Time: 10-15 minutes × 50 = 8-12 hours total (automated)
+```
+
+**4. Market Research Interviews**
+```
+Scenario: Understanding buyer preferences
+Flow: 10 questions on needs, alternatives, priorities
+AI Adaptation: Explores "price sensitivity" mentions
+Result: Market positioning insights
+Time: 25-30 minutes per interview
+```
+
+### Analysis Tips
+
+**Reviewing Transcripts:**
+1. Export all sessions after completion
+2. Look for recurring themes across conversations
+3. Note where AI follow-ups uncovered insights
+4. Compare scripted vs. dynamic question value
+
+**Processing Conversations:**
+1. **Manual Analysis**: Review transcripts for themes
+2. **Automated Analysis**: Use the "Analyze Data" tab
+   - Export conversation turns to CSV
+   - Format responses for analysis
+   - Run thematic analysis
+
+**Key Metrics:**
+- Average conversation length (turns)
+- Follow-up question frequency
+- Response depth (words per turn)
+- Topic coverage across sessions
+
+### Advanced Features
+
+**Conversation Summarization** (Coming Soon):
+- AI-generated summary of each conversation
+- Key points extraction
+- Sentiment analysis per session
+
+**Flow Branching** (Planned):
+- Conditional logic based on responses
+- Different paths for different respondent types
+- Skip logic for efficiency
+
+**Multi-Moderator Styles** (Planned):
+- Empathetic interviewer
+- Business analyst
+- Technical researcher
+- Cultural variations
+
+### Limitations
+
+**Current Limitations:**
+- ❌ Linear flows only (no branching yet)
+- ❌ Cannot resume abandoned sessions
+- ❌ One respondent per session
+- ❌ English language optimized (other languages work but less refined)
+
+**Best Suited For:**
+- ✅ Qualitative research interviews
+- ✅ Exploratory customer discovery
+- ✅ User research at scale
+- ✅ Standardized but adaptive interviews
+
+**Not Ideal For:**
+- ❌ Highly structured surveys (use static surveys instead)
+- ❌ Quantitative data collection
+- ❌ Complex branching logic requirements
+- ❌ Multi-party conversations
+
+---
+
+## 🎓 Complete Workflow Examples
+
+### Example 1: New Product Feature Research
+
+**Objective**: Understand if users want a new AI assistant feature
+
+**Step 1: Generate Survey** (5 minutes)
+```
+Outline: "Explore interest in an AI assistant feature for our
+productivity app. Focus on: use cases users envision, concerns
+about AI, willingness to pay, and preferred interaction methods."
+
+Settings:
+- Type: Mixed (qualitative + quantitative)
+- Questions: 12
+- Audience: Current users of productivity apps, tech-savvy
+```
+
+**Step 2: Deploy Survey** (You handle this)
+- Export to your survey platform
+- Send to 100 beta users
+- Collect responses over 1 week
+
+**Step 3: Translate for Global Test** (10 minutes)
+```
+Selected languages: Spanish, French, German, Japanese
+Purpose: Test with international user base
+Result: 4 localized versions ready to deploy
+```
+
+**Step 4: Analyze Results** (15 minutes)
+```
+Input: 78 responses in JSON format
+Analysis reveals:
+- 3 main use cases (writing assistance, data analysis, scheduling)
+- Positive sentiment (72%) but privacy concerns (45% mention)
+- Insights: Users willing to pay $5-10/month, prefer opt-in
+```
+
+**Total Time**: ~30 minutes of work
+**Traditional Time**: 8-12 hours
+**Savings**: ~10 hours
+
+---
+
+### Example 2: Multi-Country Market Research
+
+**Objective**: Launch product in 5 new markets, need local insights
+
+**Step 1: Generate Core Survey** (5 minutes)
+```
+Outline: "Market research for launching a sustainable fashion
+brand. Topics: sustainability priorities, price sensitivity,
+preferred materials, shopping habits, brand perception factors."
+
+Settings:
+- Type: Qualitative
+- Questions: 15
+- Audience: Environmentally conscious consumers, 25-45
+```
+
+**Step 2: Translate to Target Markets** (15 minutes)
+```
+Languages: Spanish (Mexico), Portuguese (Brazil), French (France),
+          German (Germany), Japanese (Japan)
+
+Result: 5 culturally adapted versions
+Quality check: Review by native speakers on team
+```
+
+**Step 3: Deploy and Collect** (You handle this)
+- 50 responses per country
+- 250 total responses
+- 2-week collection period
+
+**Step 4: Analyze by Market** (30 minutes)
+```
+Run analysis separately for each market:
+- Identify market-specific themes
+- Compare sentiment across markets
+- Note cultural differences in priorities
+
+Key findings example:
+- Japan: Quality and durability top priority
+- Germany: Certifications and transparency crucial
+- Brazil: Price sensitivity higher, but willing to pay for story
+```
+
+**Total Time**: ~50 minutes
+**Traditional Time**: 20-30 hours (translation + analysis)
+**Cost Savings**: $2000+ in professional services
+
+---
+
+### Example 3: Academic Research Project
+
+**Objective**: Study impact of remote work on work-life balance
+
+**Step 1: Design Survey** (10 minutes)
+```
+Outline: "Investigate how remote work affects work-life balance
+among knowledge workers. Explore: boundary management strategies,
+productivity changes, social isolation experiences, family
+dynamics, preference for future work arrangements, and mental
+health impacts."
+
+Settings:
+- Type: Qualitative (open-ended for rich data)
+- Questions: 18
+- Audience: Knowledge workers with 1+ year remote experience
+```
+
+**Step 2: Review & Refine** (20 minutes)
+- Review generated questions
+- Ensure alignment with research framework
+- Verify no leading questions
+
+**Step 3: Collect Data** (You handle this)
+- Deploy via academic participant pool
+- Collect 150 responses
+- 3-week collection period
+
+**Step 4: Comprehensive Analysis** (45 minutes)
+```
+Input: 150 detailed responses
+
+Analysis output:
+- 7 major themes with sub-themes
+- Sentiment patterns by demographic
+- 12 key insights for paper
+
+Export: Markdown report for lit review section
+       JSON for coding in qualitative software
+```
+
+**Step 5: Follow-up Translation** (Optional)
+```
+If publishing internationally or presenting at conference:
+Translate survey instrument to show methodology
+Languages: Spanish, French (common in academia)
+```
+
+**Total Time**: ~2 hours
+**Traditional Time**: 15-25 hours of manual thematic coding
+**Quality**: Comparable to manual coding for exploratory research
+
+---
+
+## 💡 Tips for Power Users
+
+### Optimizing for Quality
+
+**1. Survey Generation**
+- Iterate on outlines to get better questions
+- Generate multiple versions and combine best questions
+- Use specific examples in outlines for better context
+- Mention your theoretical framework for academic research
+
+**2. Translation**
+- Start with common languages to test quality
+- Use back-translation for critical surveys
+- Keep original English version for reference
+- Test with native speakers before full deployment
+
+**3. Analysis**
+- Provide questions JSON for better context
+- Clean data before analysis (remove duplicates, spam)
+- Run analysis multiple times for consistency
+- Combine AI insights with manual review
+
+### Optimizing for Cost
+
+**Using Free HuggingFace:**
+- Perfect for testing and development
+- Good for small-scale research (<50 responses)
+- Be patient with first request (cold start)
+- Simplify requests for better performance
+
+**Using Paid Providers:**
+
+| Provider | Best For | Cost Range | Speed |
+|----------|----------|------------|-------|
+| **OpenAI GPT-4o-mini** | Best value | $0.01-0.05/survey | Fast |
+| **OpenAI GPT-4** | Best quality | $0.05-0.15/survey | Fast |
+| **Anthropic Claude** | Complex analysis | $0.02-0.08/survey | Fast |
+
+**Cost Control Tips:**
+- Use GPT-4o-mini for generation and translation
+- Use GPT-4 only for complex analysis
+- Batch operations when possible
+- Set up usage alerts in provider dashboards
+
+### Workflow Optimization
+
+**Create Templates:**
+Save outlines for common research types:
+- Customer satisfaction surveys
+- Product feedback forms
+- Employee engagement surveys
+- User experience studies
+- Academic research instruments
+
+**Batch Processing:**
+- Generate multiple survey versions at once
+- Translate to all needed languages in one go
+- Analyze all demographics separately for comparison
+
+**Quality Checkpoints:**
+1. After generation: Review questions for bias
+2. After translation: Spot-check with native speakers
+3. After data collection: Clean data before analysis
+4. After analysis: Validate insights with domain experts
+
+---
+
+## 🔒 Privacy & Data Security
+
+### What Data is Stored?
+
+**By ConversAI:**
+- ❌ No survey data is permanently stored
+- ❌ No responses are saved to disk
+- ❌ No user information is retained
+- ✅ Temporary files for downloads only (deleted after download)
+
+**By LLM Providers:**
+- Varies by provider (check their policies)
+- OpenAI: Data not used for training by default
+- Anthropic: Enterprise plans have data guarantees
+- HuggingFace: Depends on model provider
+
+### Best Practices for Sensitive Research
+
+**1. Choose Provider Carefully**
+- For healthcare: Use HIPAA-compliant LLM service
+- For confidential: Use Anthropic or OpenAI enterprise
+- For maximum privacy: Self-host open-source models
+
+**2. Anonymize Data**
+- Remove identifying information before analysis
+- Use participant IDs instead of names
+- Redact sensitive details from responses
+
+**3. Access Control**
+- Use private HuggingFace Spaces if needed
+- Limit team access to credentials
+- Rotate API keys regularly
+
+**4. Compliance**
+- GDPR: Ensure LLM provider is compliant
+- IRB requirements: Document AI use in protocols
+- Data retention: Follow your organization's policies
+
+---
+
+## 📈 Measuring Success
+
+### Survey Generation Success Metrics
+
+✅ **Quality Indicators:**
+- Questions are unbiased and clear
+- Logical flow through survey
+- Appropriate question types used
+- All research objectives covered
+
+✅ **Efficiency Gains:**
+- Time to first draft: <5 minutes (vs. hours manually)
+- Iterations needed: 1-2 (vs. 4-5 manually)
+- Team review time reduced by 50%+
+
+### Translation Success Metrics
+
+✅ **Quality Indicators:**
+- Back-translation matches original meaning
+- Native speaker approval
+- Cultural appropriateness confirmed
+- Response rates comparable across languages
+
+✅ **Efficiency Gains:**
+- Time to translate: Minutes (vs. days/weeks)
+- Cost: Near-zero (vs. $0.10-0.30 per word)
+- Speed to market: Immediate (vs. 1-2 weeks)
+
+### Analysis Success Metrics
+
+✅ **Quality Indicators:**
+- Themes align with manual coding
+- Insights lead to actionable decisions
+- Stakeholders find report valuable
+- Findings supported by quotes
+
+✅ **Efficiency Gains:**
+- Time to insights: <1 hour (vs. 8-20 hours)
+- Cost: Minimal (vs. $500-2000 for analyst)
+- Consistency: High (vs. variable with manual coding)
+
+---
+
+## 🎯 Use Case Library
+
+### Market Research
+- **New product concept testing**: Generate survey → deploy → analyze feedback
+- **Brand perception studies**: Multi-language surveys for global brands
+- **Customer satisfaction tracking**: Quarterly analysis of feedback trends
+- **Competitive analysis**: Survey design for feature comparison studies
+
+### User Experience Research
+- **Usability study debriefs**: Analyze interview transcripts
+- **Feature prioritization**: Generate surveys for user voting
+- **Beta testing feedback**: Quick analysis of bug reports and suggestions
+- **Accessibility research**: Multi-language surveys for diverse users
+
+### Academic Research
+- **Exploratory studies**: Generate initial survey instruments
+- **Cross-cultural research**: Translate surveys for international studies
+- **Qualitative analysis**: Thematic coding of open-ended responses
+- **Mixed methods**: Combine with quantitative data collection
+
+### Human Resources
+- **Employee engagement**: Annual or pulse surveys
+- **Exit interviews**: Analysis of leaving employee feedback
+- **Training needs assessment**: Identify development opportunities
+- **Culture studies**: Understand organizational dynamics
+
+### Product Management
+- **Feature requests**: Analyze user suggestions
+- **Beta feedback**: Quick turnaround on pre-release testing
+- **Roadmap validation**: Survey users on priorities
+- **Competitor research**: Generate comparison surveys
+
+### Healthcare
+- **Patient satisfaction**: HIPAA-compliant survey generation
+- **Treatment experience**: Multi-language patient surveys
+- **Quality improvement**: Analyze patient feedback themes
+- **Clinical research**: Generate research questionnaires
+
+---
+
+## 🚧 Limitations & When NOT to Use
+
+### Current Limitations
+
+**Survey Generation:**
+- ❌ Cannot create complex branching logic
+- ❌ May need manual refinement for highly specialized topics
+- ❌ Not a replacement for expert survey design in all cases
+- ✅ Best for: Standard research surveys, exploratory studies
+
+**Translation:**
+- ❌ Not certified/legal translation quality
+- ❌ May miss subtle cultural nuances in idioms
+- ❌ Requires native speaker review for publication
+- ✅ Best for: Research surveys, internal communications
+
+**Analysis:**
+- ❌ Not a replacement for rigorous qualitative coding
+- ❌ May miss domain-specific insights
+- ❌ Cannot replace human interpretation completely
+- ✅ Best for: Initial exploration, large-scale feedback, trend identification
+
+### When to Use Traditional Methods
+
+**Use professional survey designers when:**
+- Regulatory compliance requires certified instruments
+- High-stakes research with legal implications
+- Complex adaptive survey logic needed
+- Validated scales are required
+
+**Use professional translators when:**
+- Legal or medical translations needed
+- Publishing in academic journals
+- Official government communications
+- Marketing materials with brand sensitivity
+
+**Use professional analysts when:**
+- Publishing peer-reviewed research
+- Complex coding schemes required
+- Deep domain expertise needed
+- Consensus coding is methodology requirement
+
+### Best Approach: Hybrid
+
+**Recommended workflow:**
+1. ✅ Use ConversAI for initial draft (fast, cheap)
+2. ✅ Expert review and refinement (quality assurance)
+3. ✅ Deploy and collect data
+4. ✅ ConversAI for preliminary analysis (quick insights)
+5. ✅ Deep manual analysis for key findings (rigor)
+
+---
+
+## 📞 Support & Resources
+
+### Getting Help
+
+**Documentation:**
+- `USER_GUIDE.md` (this document) - Complete user guide
+- `QUICK_START_HF_SPACES.md` - Fast deployment
+- `TROUBLESHOOTING.md` - Common issues and solutions
+- `README.md` - Technical overview
+
+**Diagnostics:**
+- Run `python check_env.py` - Environment checker
+- Check logs for error messages
+- Use example data to test functionality
+
+**Community:**
+- GitHub Issues - Report bugs and feature requests
+- HuggingFace Space discussions
+- Research methods forums
+
+### Feedback & Feature Requests
+
+We'd love to hear from you:
+- What features would make ConversAI more valuable?
+- What use cases are we missing?
+- What pain points can we solve?
+
+---
+
+## 🎓 Learning Resources
+
+### Understanding Qualitative Research
+- Introduction to thematic analysis
+- Survey design best practices
+- Avoiding bias in questions
+- Cross-cultural research methods
+
+### AI & Research Ethics
+- Using AI in research responsibly
+- Disclosing AI use in publications
+- Data privacy considerations
+- Bias in AI-generated content
+
+### Maximizing ConversAI
+- Video tutorials (coming soon)
+- Webinar series on research workflows
+- Case studies from real users
+- Best practices blog
+
+---
+
+## 🌟 Success Stories
+
+### Story 1: Startup Product Validation
+
+**Challenge**: Early-stage startup needed to validate product concept across 3 markets in 2 weeks.
+
+**Solution**:
+- Generated survey in English (10 questions)
+- Translated to Spanish and Portuguese
+- Analyzed 200+ responses in 24 hours
+
+**Results**:
+- Launched in correct market first (Brazil, not Mexico as planned)
+- Saved $3,000 in research costs
+- Made launch decision 2 weeks faster
+
+---
+
+### Story 2: University Research Project
+
+**Challenge**: PhD student analyzing 150 interview transcripts for dissertation.
+
+**Solution**:
+- Formatted transcripts as survey responses
+- Ran thematic analysis
+- Used insights as starting point for manual coding
+
+**Results**:
+- Identified 7 themes in 2 hours vs. estimated 40 hours
+- Used time savings for deeper literature review
+- Graduated on schedule
+
+---
+
+### Story 3: Enterprise Employee Engagement
+
+**Challenge**: Multinational company with 5,000 employees in 12 countries.
+
+**Solution**:
+- Generated engagement survey (20 questions)
+- Translated to 8 languages
+- Analyzed responses by region and department
+
+**Results**:
+- 40% higher response rate (due to language options)
+- Identified region-specific retention risks
+- Informed $500K investment in benefits program
+
+---
+
+## 🚀 Next Steps
+
+### New Users
+1. ✅ Start with the "Generate Survey" tab
+2. ✅ Use the example outline provided
+3. ✅ Review the generated questions
+4. ✅ Experiment with different settings
+5. ✅ Try the example data in Analysis tab
+
+### Regular Users
+1. ✅ Create outline templates for common projects
+2. ✅ Establish quality review processes
+3. ✅ Integrate into research workflow
+4. ✅ Share best practices with team
+5. ✅ Provide feedback for improvements
+
+### Advanced Users
+1. ✅ Explore API integration (coming soon)
+2. ✅ Customize LLM models for your domain
+3. ✅ Build automated research pipelines
+4. ✅ Contribute to open source development
+5. ✅ Share case studies with community
+
+---
+
+## 📋 Quick Reference
+
+### Common Tasks
+
+| Task | Location | Time | Tip |
+|------|----------|------|-----|
+| Generate survey | Generate tab | 30 sec | Be specific in outline |
+| Translate survey | Translate tab | 1-2 min | Do all languages at once |
+| Analyze responses | Analyze tab | 1 min | Min. 10 responses needed |
+| Download results | Each tab | Instant | JSON for data, MD for reports |
+
+### Quality Checklist
+
+**Before deploying survey:**
+- [ ] Questions are unbiased and clear
+- [ ] Appropriate question types used
+- [ ] Logical flow through survey
+- [ ] Introduction explains purpose
+- [ ] Pilot tested with 3-5 people
+
+**Before deploying translation:**
+- [ ] Native speaker reviewed
+- [ ] Cultural appropriateness checked
+- [ ] Technical terms verified
+- [ ] Examples make sense in target culture
+
+**Before presenting analysis:**
+- [ ] Sufficient responses (20+)
+- [ ] Themes make sense with data
+- [ ] Insights are actionable
+- [ ] Validated with domain knowledge
+- [ ] Limitations acknowledged
+
+---
+
+**ConversAI** - Transforming qualitative research with AI assistance.
+
+*Battle the blank page. Reach global audiences. Uncover insights.* 🔬
+
+---
+
+**Version**: 1.0
+**Last Updated**: 2025
+**License**: MIT
+**Support**: See TROUBLESHOOTING.md

app.py

@@ -12,13 +12,24 @@ from llm_backend import LLMBackend, LLMProvider
 from survey_generator import SurveyGenerator
 from survey_translator import SurveyTranslator
 from data_analyzer import DataAnalyzer
-from export_utils import save_json_file, survey_to_csv, analysis_to_markdown_file
+from export_utils import (save_json_file, survey_to_csv, analysis_to_markdown_file,
+                          conversation_to_transcript, conversation_to_json, conversation_to_csv,
+                          flow_to_markdown)
+from conversation_flow import ConversationFlow, ConversationNode, create_example_flow
+from conversation_session import ConversationSession, SessionManager
+from conversation_moderator import ConversationModerator
 
 
 # Global state for current survey
 current_survey = None
 current_responses = []
 
+# Global state for conversational research
+current_flow = None
+session_manager = SessionManager()
+current_session = None
+saved_flows = {}
+
 
 def initialize_backend():
     """Initialize LLM backend based on environment"""
@@ -337,6 +348,196 @@ def load_example_responses():
     return json.dumps(example, indent=2)
 
 
+# ===========================
+# Conversational Research Handlers
+# ===========================
+
+def create_new_flow(flow_name: str, flow_description: str):
+    """Create a new conversation flow"""
+    global current_flow, saved_flows
+
+    if not flow_name or not flow_name.strip():
+        return "❌ Please provide a flow name.", "", None
+
+    try:
+        flow = ConversationFlow(name=flow_name, description=flow_description)
+        current_flow = flow
+        saved_flows[flow.id] = flow
+
+        return (
+            f"✅ Flow '{flow_name}' created successfully!",
+            f"**Flow ID:** {flow.id}\n**Name:** {flow.name}\n**Description:** {flow.description}",
+            flow.id
+        )
+    except Exception as e:
+        return f"❌ Error creating flow: {str(e)}", "", None
+
+
+def load_example_flow():
+    """Load an example conversation flow"""
+    global current_flow, saved_flows
+
+    flow = create_example_flow()
+    current_flow = flow
+    saved_flows[flow.id] = flow
+
+    return (
+        f"✅ Example flow loaded: {flow.name}",
+        display_flow(flow),
+        flow.id
+    )
+
+
+def add_flow_node(flow_id: str, node_content: str, node_type: str):
+    """Add a node to the current flow"""
+    global current_flow, saved_flows
+
+    if not flow_id:
+        return "❌ No flow selected.", ""
+
+    flow = saved_flows.get(flow_id)
+    if not flow:
+        return "❌ Flow not found.", ""
+
+    if not node_content or not node_content.strip():
+        return "❌ Please provide content for the node.", ""
+
+    try:
+        node = ConversationNode(content=node_content, node_type=node_type.lower())
+
+        # Link to previous node if exists
+        if flow.nodes:
+            last_node = flow.nodes[-1]
+            last_node.next = node.id
+
+        flow.add_node(node)
+        current_flow = flow
+
+        return (
+            f"✅ Node added successfully! Total nodes: {len(flow.nodes)}",
+            display_flow(flow)
+        )
+    except Exception as e:
+        return f"❌ Error adding node: {str(e)}", ""
+
+
+def display_flow(flow: ConversationFlow) -> str:
+    """Display flow as markdown"""
+    if not flow or not flow.nodes:
+        return "No flow to display"
+
+    output = f"# {flow.name}\n\n"
+    output += f"**Description:** {flow.description}\n\n"
+    output += f"**Total Steps:** {len(flow.nodes)}\n\n"
+    output += "---\n\n"
+
+    for i, node in enumerate(flow.nodes, 1):
+        output += f"### Step {i}: {node.type.capitalize()}\n\n"
+        output += f"{node.content}\n\n"
+
+    return output
+
+
+def save_current_flow(flow_id: str):
+    """Save the current flow to file"""
+    if not flow_id:
+        return "❌ No flow selected.", None
+
+    flow = saved_flows.get(flow_id)
+    if not flow:
+        return "❌ Flow not found.", None
+
+    try:
+        filepath = save_json_file(flow.to_dict(), "conversation_flow")
+        return f"✅ Flow saved to {filepath}", filepath
+    except Exception as e:
+        return f"❌ Error saving flow: {str(e)}", None
+
+
+def start_conversation_session(flow_id: str):
+    """Start a new conversation session"""
+    global current_session, session_manager
+
+    if not flow_id:
+        return [], "❌ Please select a flow first."
+
+    flow = saved_flows.get(flow_id)
+    if not flow:
+        return [], "❌ Flow not found."
+
+    if not llm_backend:
+        return [], "❌ LLM backend not initialized."
+
+    try:
+        # Create session
+        session = session_manager.create_session(flow_id=flow.id, flow_name=flow.name)
+        current_session = session
+
+        # Create moderator
+        moderator = ConversationModerator(llm_backend, flow)
+
+        # Start conversation
+        opening_message = moderator.start_conversation(session)
+
+        # Return chat history in Gradio format
+        return [[None, opening_message]], f"✅ Conversation started! Session ID: {session.id}"
+
+    except Exception as e:
+        return [], f"❌ Error starting conversation: {str(e)}"
+
+
+def chat_with_moderator(user_message: str, history: List):
+    """Handle chat messages with the AI moderator"""
+    global current_session
+
+    if not current_session:
+        return history, "❌ No active session. Please start a conversation first."
+
+    if not llm_backend:
+        return history, "❌ LLM backend not initialized."
+
+    if not user_message or not user_message.strip():
+        return history, "❌ Please enter a message."
+
+    try:
+        # Get the flow
+        flow = saved_flows.get(current_session.flow_id)
+        if not flow:
+            return history, "❌ Flow not found."
+
+        # Create moderator
+        moderator = ConversationModerator(llm_backend, flow)
+
+        # Process user response
+        ai_response = moderator.process_user_response(current_session, user_message)
+
+        # Update history
+        history.append([user_message, ai_response])
+
+        status = f"Session: {current_session.id} | Turns: {current_session.get_turn_count()}"
+        if current_session.status == "completed":
+            status += " | ✅ Conversation completed"
+
+        return history, status
+
+    except Exception as e:
+        return history, f"❌ Error: {str(e)}"
+
+
+def export_conversation():
+    """Export the current conversation"""
+    global current_session
+
+    if not current_session:
+        return "❌ No active session to export.", None
+
+    try:
+        filepath = conversation_to_transcript(current_session)
+        return f"✅ Conversation exported to {filepath}", filepath
+    except Exception as e:
+        return f"❌ Error exporting conversation: {str(e)}", None
+
+
 # ===========================
 # Gradio Interface
 # ===========================
@@ -523,6 +724,202 @@ See the **About** tab for detailed instructions."""
                     outputs=[responses_input]
                 )
 
+            # ========== CONVERSATIONAL RESEARCH TAB ==========
+            with gr.Tab("💬 Conversational Research"):
+                gr.Markdown("""
+                ## AI-Moderated Conversations
+                Design conversation flows and conduct AI-powered qualitative interviews with respondents.
+                """)
+
+                with gr.Tabs():
+                    # Design Flow Sub-Tab
+                    with gr.Tab("🎨 Design Flow"):
+                        gr.Markdown("""
+                        ### Create Conversation Flows
+                        Design custom conversation paths for AI-moderated interviews.
+                        """)
+
+                        with gr.Row():
+                            with gr.Column(scale=1):
+                                gr.Markdown("#### Flow Setup")
+
+                                flow_name_input = gr.Textbox(
+                                    label="Flow Name",
+                                    placeholder="e.g., HCP Interview for New Dermatology Product",
+                                    value=""
+                                )
+
+                                flow_desc_input = gr.Textbox(
+                                    label="Flow Description",
+                                    placeholder="Describe the purpose of this conversation flow...",
+                                    lines=3
+                                )
+
+                                with gr.Row():
+                                    create_flow_btn = gr.Button("✨ Create New Flow", variant="primary")
+                                    load_example_flow_btn = gr.Button("📋 Load Example", variant="secondary")
+
+                                flow_id_state = gr.State(value="")
+
+                                gr.Markdown("#### Add Steps to Flow")
+
+                                node_content_input = gr.Textbox(
+                                    label="Question/Message",
+                                    placeholder="Enter the question or message for this step...",
+                                    lines=4
+                                )
+
+                                node_type_input = gr.Radio(
+                                    label="Step Type",
+                                    choices=["Question", "End"],
+                                    value="Question"
+                                )
+
+                                add_node_btn = gr.Button("➕ Add Step", variant="secondary")
+
+                                save_flow_btn = gr.Button("💾 Save Flow", variant="primary")
+
+                            with gr.Column(scale=1):
+                                flow_status = gr.Textbox(label="Status", interactive=False)
+                                flow_display = gr.Markdown(label="Flow Preview", value="No flow created yet")
+
+                        flow_download = gr.File(label="Download Flow JSON", visible=False)
+
+                        # Event handlers for flow design
+                        create_flow_btn.click(
+                            fn=create_new_flow,
+                            inputs=[flow_name_input, flow_desc_input],
+                            outputs=[flow_status, flow_display, flow_id_state]
+                        )
+
+                        load_example_flow_btn.click(
+                            fn=load_example_flow,
+                            outputs=[flow_status, flow_display, flow_id_state]
+                        )
+
+                        add_node_btn.click(
+                            fn=add_flow_node,
+                            inputs=[flow_id_state, node_content_input, node_type_input],
+                            outputs=[flow_status, flow_display]
+                        ).then(
+                            fn=lambda: "",
+                            outputs=[node_content_input]
+                        )
+
+                        save_flow_btn.click(
+                            fn=save_current_flow,
+                            inputs=[flow_id_state],
+                            outputs=[flow_status, flow_download]
+                        ).then(
+                            fn=lambda x: gr.File(value=x, visible=True) if x else gr.File(visible=False),
+                            inputs=[flow_download],
+                            outputs=[flow_download]
+                        )
+
+                    # Conduct Interview Sub-Tab
+                    with gr.Tab("🎙️ Conduct Interview"):
+                        gr.Markdown("""
+                        ### AI-Moderated Interview
+                        Start a conversation session with the AI moderator using your designed flow.
+                        """)
+
+                        with gr.Row():
+                            with gr.Column(scale=1):
+                                conversation_flow_selector = gr.State(value="")
+
+                                gr.Markdown("""
+                                **Instructions:**
+                                1. Design a flow in the 'Design Flow' tab first (or load the example)
+                                2. Click 'Start Conversation' to begin
+                                3. The AI moderator will ask questions from your flow
+                                4. The AI adapts with follow-up questions based on responses
+                                5. Export the conversation when finished
+                                """)
+
+                                with gr.Row():
+                                    start_conversation_btn = gr.Button("🚀 Start Conversation", variant="primary")
+                                    export_conversation_btn = gr.Button("📥 Export Conversation", variant="secondary")
+
+                                conversation_status = gr.Textbox(label="Session Status", interactive=False)
+                                conversation_download = gr.File(label="Download Transcript", visible=False)
+
+                            with gr.Column(scale=1):
+                                chatbot = gr.Chatbot(
+                                    label="AI-Moderated Interview",
+                                    height=500
+                                )
+
+                                msg_input = gr.Textbox(
+                                    label="Your Response",
+                                    placeholder="Type your response here...",
+                                    lines=2
+                                )
+
+                                with gr.Row():
+                                    submit_btn = gr.Button("Send", variant="primary")
+                                    clear_btn = gr.Button("Clear")
+
+                        # Chat event handlers
+                        def user_submit(user_message, history):
+                            """Handle user message submission"""
+                            if not user_message:
+                                return history, history, ""
+                            return history, history + [[user_message, None]], ""
+
+                        def bot_respond(history):
+                            """Get bot response"""
+                            if not history or history[-1][1] is not None:
+                                return history, ""
+
+                            user_msg = history[-1][0]
+                            updated_history, status = chat_with_moderator(user_msg, history[:-1])
+                            return updated_history, status
+
+                        # Start conversation
+                        start_conversation_btn.click(
+                            fn=lambda: saved_flows[list(saved_flows.keys())[-1]].id if saved_flows else "",
+                            outputs=[conversation_flow_selector]
+                        ).then(
+                            fn=start_conversation_session,
+                            inputs=[conversation_flow_selector],
+                            outputs=[chatbot, conversation_status]
+                        )
+
+                        # Message submission
+                        msg_input.submit(
+                            fn=user_submit,
+                            inputs=[msg_input, chatbot],
+                            outputs=[chatbot, chatbot, msg_input],
+                            queue=False
+                        ).then(
+                            fn=bot_respond,
+                            inputs=[chatbot],
+                            outputs=[chatbot, conversation_status]
+                        )
+
+                        submit_btn.click(
+                            fn=user_submit,
+                            inputs=[msg_input, chatbot],
+                            outputs=[chatbot, chatbot, msg_input],
+                            queue=False
+                        ).then(
+                            fn=bot_respond,
+                            inputs=[chatbot],
+                            outputs=[chatbot, conversation_status]
+                        )
+
+                        clear_btn.click(lambda: None, None, chatbot, queue=False)
+
+                        # Export conversation
+                        export_conversation_btn.click(
+                            fn=export_conversation,
+                            outputs=[conversation_status, conversation_download]
+                        ).then(
+                            fn=lambda x: gr.File(value=x, visible=True) if x else gr.File(visible=False),
+                            inputs=[conversation_download],
+                            outputs=[conversation_download]
+                        )
+
             # ========== ABOUT TAB ==========
             with gr.Tab("ℹ️ About"):
                 gr.Markdown("""

conversation_flow.py

@@ -0,0 +1,197 @@
+"""
+Conversation Flow Management - Design and store conversation paths
+"""
+import json
+import uuid
+from typing import Dict, List, Optional
+from datetime import datetime
+
+
+class ConversationNode:
+    """Represents a single node in a conversation flow"""
+
+    def __init__(self, node_id: str = None, node_type: str = "question",
+                 content: str = "", next_node: str = None, branches: List[Dict] = None):
+        self.id = node_id or str(uuid.uuid4())
+        self.type = node_type  # "question", "branch", "end"
+        self.content = content
+        self.next = next_node
+        self.branches = branches or []  # For conditional branching
+
+    def to_dict(self) -> Dict:
+        """Convert node to dictionary"""
+        return {
+            "id": self.id,
+            "type": self.type,
+            "content": self.content,
+            "next": self.next,
+            "branches": self.branches
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> 'ConversationNode':
+        """Create node from dictionary"""
+        return cls(
+            node_id=data.get("id"),
+            node_type=data.get("type", "question"),
+            content=data.get("content", ""),
+            next_node=data.get("next"),
+            branches=data.get("branches", [])
+        )
+
+
+class ConversationFlow:
+    """Manages a complete conversation flow"""
+
+    def __init__(self, flow_id: str = None, name: str = "Untitled Flow",
+                 description: str = "", nodes: List[ConversationNode] = None):
+        self.id = flow_id or str(uuid.uuid4())
+        self.name = name
+        self.description = description
+        self.nodes = nodes or []
+        self.created_at = datetime.now().isoformat()
+        self.updated_at = datetime.now().isoformat()
+
+    def add_node(self, node: ConversationNode, position: int = None):
+        """Add a node to the flow"""
+        if position is None:
+            self.nodes.append(node)
+        else:
+            self.nodes.insert(position, node)
+        self.updated_at = datetime.now().isoformat()
+
+    def remove_node(self, node_id: str):
+        """Remove a node from the flow"""
+        self.nodes = [n for n in self.nodes if n.id != node_id]
+        self.updated_at = datetime.now().isoformat()
+
+    def get_node(self, node_id: str) -> Optional[ConversationNode]:
+        """Get a node by ID"""
+        for node in self.nodes:
+            if node.id == node_id:
+                return node
+        return None
+
+    def get_start_node(self) -> Optional[ConversationNode]:
+        """Get the first node in the flow"""
+        return self.nodes[0] if self.nodes else None
+
+    def reorder_node(self, node_id: str, new_position: int):
+        """Move a node to a different position"""
+        node = self.get_node(node_id)
+        if node:
+            self.nodes.remove(node)
+            self.nodes.insert(new_position, node)
+            self.updated_at = datetime.now().isoformat()
+
+    def to_dict(self) -> Dict:
+        """Convert flow to dictionary"""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "nodes": [node.to_dict() for node in self.nodes],
+            "created_at": self.created_at,
+            "updated_at": self.updated_at
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> 'ConversationFlow':
+        """Create flow from dictionary"""
+        flow = cls(
+            flow_id=data.get("id"),
+            name=data.get("name", "Untitled Flow"),
+            description=data.get("description", "")
+        )
+        flow.nodes = [ConversationNode.from_dict(n) for n in data.get("nodes", [])]
+        flow.created_at = data.get("created_at", datetime.now().isoformat())
+        flow.updated_at = data.get("updated_at", datetime.now().isoformat())
+        return flow
+
+    def save_to_file(self, filepath: str):
+        """Save flow to JSON file"""
+        with open(filepath, 'w') as f:
+            json.dump(self.to_dict(), f, indent=2)
+
+    @classmethod
+    def load_from_file(cls, filepath: str) -> 'ConversationFlow':
+        """Load flow from JSON file"""
+        with open(filepath, 'r') as f:
+            data = json.load(f)
+        return cls.from_dict(data)
+
+    def validate(self) -> tuple[bool, str]:
+        """Validate the flow structure"""
+        if not self.nodes:
+            return False, "Flow must have at least one node"
+
+        if not self.name or not self.name.strip():
+            return False, "Flow must have a name"
+
+        # Check for orphaned nodes (nodes that can't be reached)
+        reachable = set()
+        if self.nodes:
+            current = self.nodes[0]
+            reachable.add(current.id)
+
+            # Simple validation: check if nodes are in sequence
+            for node in self.nodes:
+                if not node.content or not node.content.strip():
+                    return False, f"Node {node.id} has no content"
+
+        return True, "Flow is valid"
+
+
+def create_example_flow() -> ConversationFlow:
+    """Create an example conversation flow"""
+    flow = ConversationFlow(
+        name="Customer Feedback Interview",
+        description="Structured interview to gather customer feedback on product experience"
+    )
+
+    # Add nodes
+    node1 = ConversationNode(
+        content="Hello! Thank you for taking the time to speak with me today. I'd like to understand your experience with our product. First, can you tell me what initially attracted you to our product?",
+        node_type="question"
+    )
+
+    node2 = ConversationNode(
+        content="That's interesting. How would you describe your overall experience using the product so far?",
+        node_type="question"
+    )
+
+    node3 = ConversationNode(
+        content="What specific features do you find most valuable, and why?",
+        node_type="question"
+    )
+
+    node4 = ConversationNode(
+        content="Have you encountered any challenges or frustrations while using the product? If so, can you describe them?",
+        node_type="question"
+    )
+
+    node5 = ConversationNode(
+        content="Based on your experience, what improvements or new features would you most like to see?",
+        node_type="question"
+    )
+
+    node6 = ConversationNode(
+        content="Thank you so much for sharing your thoughts! Your feedback is incredibly valuable and will help us improve the product. Is there anything else you'd like to add?",
+        node_type="end"
+    )
+
+    # Link nodes
+    node1.next = node2.id
+    node2.next = node3.id
+    node3.next = node4.id
+    node4.next = node5.id
+    node5.next = node6.id
+
+    flow.add_node(node1)
+    flow.add_node(node2)
+    flow.add_node(node3)
+    flow.add_node(node4)
+    flow.add_node(node5)
+    flow.add_node(node6)
+
+    return flow

conversation_moderator.py

@@ -0,0 +1,243 @@
+"""
+Conversation Moderator - AI-powered interview moderator
+"""
+from typing import Dict, List, Optional, Tuple
+from llm_backend import LLMBackend
+from conversation_flow import ConversationFlow, ConversationNode
+from conversation_session import ConversationSession
+
+
+class ConversationModerator:
+    """
+    AI moderator that conducts conversations based on flows.
+    Handles scripted questions, dynamic follow-ups, and probing.
+    """
+
+    def __init__(self, llm_backend: LLMBackend, flow: ConversationFlow):
+        self.llm = llm_backend
+        self.flow = flow
+        self.follow_up_threshold = 3  # Ask follow-up every N user responses
+
+    def start_conversation(self, session: ConversationSession) -> str:
+        """
+        Start a conversation by asking the first question.
+
+        Returns:
+            The opening message from the AI
+        """
+        first_node = self.flow.get_start_node()
+        if not first_node:
+            return "I apologize, but there seems to be an issue with the conversation flow."
+
+        session.current_node_id = first_node.id
+        session.add_turn("ai", first_node.content, node_id=first_node.id)
+        return first_node.content
+
+    def process_user_response(self, session: ConversationSession, user_message: str) -> str:
+        """
+        Process a user response and generate the next AI message.
+
+        Args:
+            session: Current conversation session
+            user_message: The user's message
+
+        Returns:
+            The AI's response
+        """
+        # Add user message to session
+        session.add_turn("user", user_message)
+
+        # Decide whether to ask scripted question or dynamic follow-up
+        if self._should_probe(session, user_message):
+            # Generate dynamic follow-up question
+            ai_response = self._generate_follow_up(session, user_message)
+            session.add_turn("ai", ai_response)
+        else:
+            # Move to next node in flow
+            ai_response = self._get_next_scripted_question(session)
+            if ai_response:
+                session.add_turn("ai", ai_response, node_id=session.current_node_id)
+            else:
+                # End of flow
+                ai_response = self._generate_closing(session)
+                session.add_turn("ai", ai_response)
+                session.end_session()
+
+        return ai_response
+
+    def _should_probe(self, session: ConversationSession, user_message: str) -> bool:
+        """
+        Decide if we should probe deeper or continue with scripted questions.
+
+        Returns:
+            True if should ask follow-up, False if should continue flow
+        """
+        # Don't probe on very short responses
+        if len(user_message.split()) < 5:
+            return False
+
+        # Probe every few responses (but not too often)
+        user_turns = [t for t in session.conversation_history if t.role == "user"]
+        turn_count = len(user_turns)
+
+        # Probe on turns 2, 5, 8, etc. (every 3 turns, starting after first question)
+        if turn_count > 1 and (turn_count - 1) % self.follow_up_threshold == 0:
+            return True
+
+        # Also probe if response contains interesting keywords
+        interesting_keywords = [
+            "because", "however", "although", "surprisingly", "unfortunately",
+            "frustrated", "confused", "excited", "worried", "concerned"
+        ]
+        if any(keyword in user_message.lower() for keyword in interesting_keywords):
+            return True
+
+        return False
+
+    def _generate_follow_up(self, session: ConversationSession, user_message: str) -> str:
+        """
+        Generate a dynamic follow-up question using the LLM.
+
+        Args:
+            session: Current conversation session
+            user_message: The user's latest message
+
+        Returns:
+            A follow-up question
+        """
+        # Create prompt for generating follow-up
+        system_prompt = """You are a professional qualitative research interviewer. Your goal is to probe deeper into the respondent's answers to uncover insights.
+
+Generate ONE follow-up question that:
+- Explores an interesting point the respondent mentioned
+- Asks for more detail or clarification
+- Uses phrases like "Tell me more about...", "Can you elaborate on...", "What do you mean by...", "Why do you think..."
+- Is empathetic and non-judgmental
+- Is concise (one sentence)
+
+Respond ONLY with the follow-up question, nothing else."""
+
+        user_prompt = f"""The respondent just said: "{user_message}"
+
+Generate a single follow-up question to probe deeper into their response."""
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt}
+        ]
+
+        try:
+            follow_up = self.llm.generate(messages, max_tokens=100, temperature=0.7)
+            # Clean up the response
+            follow_up = follow_up.strip().strip('"').strip("'")
+            if not follow_up.endswith("?"):
+                follow_up += "?"
+            return follow_up
+        except Exception as e:
+            # Fallback to generic follow-up
+            return "Can you tell me more about that?"
+
+    def _get_next_scripted_question(self, session: ConversationSession) -> Optional[str]:
+        """
+        Get the next scripted question from the flow.
+
+        Returns:
+            The next question, or None if end of flow
+        """
+        if not session.current_node_id:
+            return None
+
+        current_node = self.flow.get_node(session.current_node_id)
+        if not current_node or not current_node.next:
+            return None
+
+        next_node = self.flow.get_node(current_node.next)
+        if not next_node:
+            return None
+
+        session.current_node_id = next_node.id
+        return next_node.content
+
+    def _generate_closing(self, session: ConversationSession) -> str:
+        """
+        Generate a closing message for the conversation.
+
+        Returns:
+            Closing message
+        """
+        return "Thank you so much for sharing your thoughts with me today. Your insights are incredibly valuable and will help us better understand this topic. Is there anything else you'd like to add before we finish?"
+
+    def generate_summary(self, session: ConversationSession) -> str:
+        """
+        Generate a summary of the conversation using the LLM.
+
+        Args:
+            session: The conversation session to summarize
+
+        Returns:
+            A summary of the conversation
+        """
+        # Get conversation transcript
+        transcript_parts = []
+        for turn in session.conversation_history:
+            speaker = "Moderator" if turn.role == "ai" else "Respondent"
+            transcript_parts.append(f"{speaker}: {turn.content}")
+
+        transcript = "\n".join(transcript_parts)
+
+        system_prompt = """You are analyzing a qualitative research interview. Generate a concise summary that captures:
+1. The main topics discussed
+2. Key insights or themes from the respondent
+3. Notable quotes or moments
+4. Overall sentiment
+
+Keep the summary to 3-4 paragraphs."""
+
+        user_prompt = f"""Summarize this interview:
+
+{transcript}
+
+Provide a professional summary suitable for a research report."""
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt}
+        ]
+
+        try:
+            summary = self.llm.generate(messages, max_tokens=500, temperature=0.5)
+            return summary.strip()
+        except Exception as e:
+            return f"Summary generation failed: {str(e)}"
+
+    def reflect_understanding(self, session: ConversationSession) -> str:
+        """
+        Periodically reflect back understanding to the respondent.
+
+        Returns:
+            A reflection statement
+        """
+        recent_turns = [t for t in session.conversation_history if t.role == "user"][-3:]
+        if not recent_turns:
+            return "Let me make sure I understand you correctly..."
+
+        recent_content = " ".join([t.content for t in recent_turns])
+
+        system_prompt = """You are a research interviewer reflecting back what you've heard. Create a brief summary (1-2 sentences) of what the respondent has shared, then ask if you understood correctly.
+
+Format: "So if I understand correctly, [summary]. Is that right?" """
+
+        user_prompt = f"""The respondent recently said: "{recent_content}"
+
+Reflect back your understanding and ask for confirmation."""
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt}
+        ]
+
+        try:
+            reflection = self.llm.generate(messages, max_tokens=150, temperature=0.5)
+            return reflection.strip()
+        except Exception as e:
+            return "Let me make sure I understand you correctly - can you confirm that I've captured your main points accurately?"

conversation_session.py

@@ -0,0 +1,226 @@
+"""
+Conversation Session Management - Track live conversations
+"""
+import json
+import uuid
+from typing import Dict, List, Optional
+from datetime import datetime
+
+
+class ConversationTurn:
+    """Represents a single turn in a conversation"""
+
+    def __init__(self, role: str, content: str, timestamp: str = None,
+                 node_id: str = None, summary: str = None):
+        self.role = role  # "ai" or "user"
+        self.content = content
+        self.timestamp = timestamp or datetime.now().isoformat()
+        self.node_id = node_id  # Which node in the flow this relates to
+        self.summary = summary  # AI's summary of this turn
+
+    def to_dict(self) -> Dict:
+        """Convert turn to dictionary"""
+        return {
+            "role": self.role,
+            "content": self.content,
+            "timestamp": self.timestamp,
+            "node_id": self.node_id,
+            "summary": self.summary
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> 'ConversationTurn':
+        """Create turn from dictionary"""
+        return cls(
+            role=data.get("role"),
+            content=data.get("content"),
+            timestamp=data.get("timestamp"),
+            node_id=data.get("node_id"),
+            summary=data.get("summary")
+        )
+
+
+class ConversationSession:
+    """Manages a live conversation session"""
+
+    def __init__(self, session_id: str = None, flow_id: str = None,
+                 respondent_id: str = None, flow_name: str = ""):
+        self.id = session_id or str(uuid.uuid4())
+        self.flow_id = flow_id
+        self.flow_name = flow_name
+        self.respondent_id = respondent_id or f"respondent_{uuid.uuid4().hex[:8]}"
+        self.conversation_history: List[ConversationTurn] = []
+        self.current_node_id: Optional[str] = None
+        self.started_at = datetime.now().isoformat()
+        self.ended_at: Optional[str] = None
+        self.status = "active"  # "active", "completed", "abandoned"
+        self.metadata = {}
+
+    def add_turn(self, role: str, content: str, node_id: str = None, summary: str = None):
+        """Add a turn to the conversation"""
+        turn = ConversationTurn(
+            role=role,
+            content=content,
+            node_id=node_id,
+            summary=summary
+        )
+        self.conversation_history.append(turn)
+
+    def get_conversation_for_llm(self) -> List[Dict[str, str]]:
+        """Get conversation history in format suitable for LLM"""
+        messages = []
+        for turn in self.conversation_history:
+            messages.append({
+                "role": "assistant" if turn.role == "ai" else "user",
+                "content": turn.content
+            })
+        return messages
+
+    def get_last_user_message(self) -> Optional[str]:
+        """Get the most recent user message"""
+        for turn in reversed(self.conversation_history):
+            if turn.role == "user":
+                return turn.content
+        return None
+
+    def get_turn_count(self) -> int:
+        """Get total number of turns"""
+        return len(self.conversation_history)
+
+    def end_session(self):
+        """Mark session as completed"""
+        self.status = "completed"
+        self.ended_at = datetime.now().isoformat()
+
+    def abandon_session(self):
+        """Mark session as abandoned"""
+        self.status = "abandoned"
+        self.ended_at = datetime.now().isoformat()
+
+    def to_dict(self) -> Dict:
+        """Convert session to dictionary"""
+        return {
+            "id": self.id,
+            "flow_id": self.flow_id,
+            "flow_name": self.flow_name,
+            "respondent_id": self.respondent_id,
+            "conversation_history": [turn.to_dict() for turn in self.conversation_history],
+            "current_node_id": self.current_node_id,
+            "started_at": self.started_at,
+            "ended_at": self.ended_at,
+            "status": self.status,
+            "metadata": self.metadata
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> 'ConversationSession':
+        """Create session from dictionary"""
+        session = cls(
+            session_id=data.get("id"),
+            flow_id=data.get("flow_id"),
+            respondent_id=data.get("respondent_id"),
+            flow_name=data.get("flow_name", "")
+        )
+        session.conversation_history = [
+            ConversationTurn.from_dict(t) for t in data.get("conversation_history", [])
+        ]
+        session.current_node_id = data.get("current_node_id")
+        session.started_at = data.get("started_at", datetime.now().isoformat())
+        session.ended_at = data.get("ended_at")
+        session.status = data.get("status", "active")
+        session.metadata = data.get("metadata", {})
+        return session
+
+    def save_to_file(self, filepath: str):
+        """Save session to JSON file"""
+        with open(filepath, 'w') as f:
+            json.dump(self.to_dict(), f, indent=2)
+
+    @classmethod
+    def load_from_file(cls, filepath: str) -> 'ConversationSession':
+        """Load session from JSON file"""
+        with open(filepath, 'r') as f:
+            data = json.load(f)
+        return cls.from_dict(data)
+
+    def get_transcript(self) -> str:
+        """Get conversation as readable transcript"""
+        lines = []
+        lines.append(f"Conversation Session: {self.id}")
+        lines.append(f"Flow: {self.flow_name}")
+        lines.append(f"Respondent: {self.respondent_id}")
+        lines.append(f"Started: {self.started_at}")
+        if self.ended_at:
+            lines.append(f"Ended: {self.ended_at}")
+        lines.append(f"Status: {self.status}")
+        lines.append("\n" + "="*60 + "\n")
+
+        for i, turn in enumerate(self.conversation_history, 1):
+            speaker = "AI Moderator" if turn.role == "ai" else "Respondent"
+            lines.append(f"[{i}] {speaker} ({turn.timestamp}):")
+            lines.append(f"{turn.content}\n")
+
+            if turn.summary:
+                lines.append(f"   Summary: {turn.summary}\n")
+
+        return "\n".join(lines)
+
+    def get_summary_stats(self) -> Dict:
+        """Get summary statistics about the session"""
+        user_turns = [t for t in self.conversation_history if t.role == "user"]
+        ai_turns = [t for t in self.conversation_history if t.role == "ai"]
+
+        return {
+            "total_turns": len(self.conversation_history),
+            "user_turns": len(user_turns),
+            "ai_turns": len(ai_turns),
+            "avg_user_response_length": sum(len(t.content) for t in user_turns) / max(len(user_turns), 1),
+            "duration_minutes": self._calculate_duration_minutes(),
+            "status": self.status
+        }
+
+    def _calculate_duration_minutes(self) -> float:
+        """Calculate session duration in minutes"""
+        if not self.ended_at:
+            end_time = datetime.now()
+        else:
+            end_time = datetime.fromisoformat(self.ended_at)
+
+        start_time = datetime.fromisoformat(self.started_at)
+        duration = (end_time - start_time).total_seconds() / 60
+        return round(duration, 2)
+
+
+class SessionManager:
+    """Manages multiple conversation sessions"""
+
+    def __init__(self):
+        self.sessions: Dict[str, ConversationSession] = {}
+
+    def create_session(self, flow_id: str, flow_name: str = "", respondent_id: str = None) -> ConversationSession:
+        """Create a new session"""
+        session = ConversationSession(
+            flow_id=flow_id,
+            flow_name=flow_name,
+            respondent_id=respondent_id
+        )
+        self.sessions[session.id] = session
+        return session
+
+    def get_session(self, session_id: str) -> Optional[ConversationSession]:
+        """Get a session by ID"""
+        return self.sessions.get(session_id)
+
+    def get_active_sessions(self) -> List[ConversationSession]:
+        """Get all active sessions"""
+        return [s for s in self.sessions.values() if s.status == "active"]
+
+    def get_all_sessions(self) -> List[ConversationSession]:
+        """Get all sessions"""
+        return list(self.sessions.values())
+
+    def end_session(self, session_id: str):
+        """End a session"""
+        session = self.sessions.get(session_id)
+        if session:
+            session.end_session()

export_utils.py

@@ -136,3 +136,108 @@ def create_survey_package(survey_data: Dict) -> Dict[str, str]:
     package['csv'] = survey_to_csv(survey_data)
 
     return package
+
+
+def conversation_to_transcript(conversation_session) -> str:
+    """
+    Export conversation session as readable text transcript.
+
+    Args:
+        conversation_session: ConversationSession object
+
+    Returns:
+        Path to transcript file
+    """
+    transcript = conversation_session.get_transcript()
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"conversation_transcript_{timestamp}.txt"
+
+    with open(filename, 'w', encoding='utf-8') as f:
+        f.write(transcript)
+
+    return filename
+
+
+def conversation_to_json(conversation_session) -> str:
+    """
+    Export conversation session as JSON.
+
+    Args:
+        conversation_session: ConversationSession object
+
+    Returns:
+        Path to JSON file
+    """
+    return save_json_file(conversation_session.to_dict(), "conversation_session")
+
+
+def conversation_to_csv(conversation_session) -> str:
+    """
+    Export conversation turns as CSV.
+
+    Args:
+        conversation_session: ConversationSession object
+
+    Returns:
+        Path to CSV file
+    """
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"conversation_{timestamp}.csv"
+
+    with open(filename, 'w', newline='', encoding='utf-8') as f:
+        writer = csv.writer(f)
+
+        # Write header
+        writer.writerow(['Turn', 'Speaker', 'Timestamp', 'Content', 'Node ID', 'Summary'])
+
+        # Write turns
+        for i, turn in enumerate(conversation_session.conversation_history, 1):
+            speaker = "AI Moderator" if turn.role == "ai" else "Respondent"
+            writer.writerow([
+                i,
+                speaker,
+                turn.timestamp,
+                turn.content,
+                turn.node_id or '',
+                turn.summary or ''
+            ])
+
+    return filename
+
+
+def flow_to_markdown(conversation_flow) -> str:
+    """
+    Export conversation flow as markdown document.
+
+    Args:
+        conversation_flow: ConversationFlow object
+
+    Returns:
+        Path to markdown file
+    """
+    lines = []
+    lines.append(f"# {conversation_flow.name}\n")
+    lines.append(f"**Description:** {conversation_flow.description}\n")
+    lines.append(f"**Created:** {conversation_flow.created_at}")
+    lines.append(f"**Updated:** {conversation_flow.updated_at}\n")
+    lines.append("\n## Conversation Flow\n")
+
+    for i, node in enumerate(conversation_flow.nodes, 1):
+        lines.append(f"### Step {i}: {node.type.capitalize()}\n")
+        lines.append(f"**Content:** {node.content}\n")
+        if node.next:
+            lines.append(f"**Next Node:** {node.next}\n")
+        if node.branches:
+            lines.append(f"**Branches:** {len(node.branches)}\n")
+        lines.append("")
+
+    content = "\n".join(lines)
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"conversation_flow_{timestamp}.md"
+
+    with open(filename, 'w', encoding='utf-8') as f:
+        f.write(content)
+
+    return filename