Skip to content

Latest commit

 

History

History
281 lines (235 loc) · 10.2 KB

FAQ.md

File metadata and controls

281 lines (235 loc) · 10.2 KB

Frequently Asked Questions

Common Issues, Solutions, and Support for Clarity

🚀 Installation & Setup

Q: How do I get started with Clarity?

A: Follow these steps:

  1. Choose your mode:
    • Demo Mode: Quick testing (requires internet)
    • Ollama Mode: Local processing (recommended)
    • Local Model: Full offline (maximum privacy)
  2. Complete onboarding in the web interface
  3. Import model or configure Ollama
  4. Start chatting with your privacy-first AI partner

Q: What are the system requirements?

A: Minimum requirements:

  • RAM: 4GB (8GB+ recommended)
  • Storage: 2GB free space (10GB+ for models)
  • Browser: Chrome 113+, Edge 113+, Firefox 100+, Safari 16+
  • OS: Windows 10+, macOS 10.15+, Linux (modern)

Q: Which mode should I choose?

A: It depends on your needs:

  • Demo Mode: Quick testing, demos, no setup required
  • Ollama Mode: Best balance of privacy and performance
  • Local Model: Maximum privacy, requires model download

🔧 Technical Issues

Q: Model import fails - what should I do?

A: Try these solutions:

  1. Check file format: Must be .gguf extension
  2. Verify file size: Between 100MB and 15GB
  3. Clear browser storage: Free up space
  4. Try different browser: Chrome/Edge work best
  5. Check console errors: F12 → Console tab

Q: "Storage quota exceeded" error

A: Solutions:

  1. Clear browser data: Settings → Privacy → Clear browsing data
  2. Close other tabs: Free up memory
  3. Try different browser: Some browsers have higher limits
  4. Use smaller model: Try E2B instead of E4B
  5. Check disk space: Ensure 5GB+ free space

Q: "File too large" or "File too small" error

A: File requirements:

  • Minimum size: 100MB
  • Maximum size: 15GB
  • Format: .gguf files only
  • Source: Download from Hugging Face, LM Studio, or Ollama

Q: Voice input doesn't work

A: Voice input limitations:

  • Browser Support: Chrome/Edge (best), Safari (limited), Firefox (not supported)
  • HTTPS Required: Some browsers require HTTPS for microphone access
  • Permissions: Allow microphone access when prompted
  • Fallback: Use text input if voice doesn't work

Q: App crashes or freezes

A: Troubleshooting steps:

  1. Refresh page: Hard refresh (Ctrl+F5)
  2. Clear browser cache: Clear all site data
  3. Close other tabs: Free up memory
  4. Restart browser: Close and reopen
  5. Check RAM usage: Ensure sufficient memory available

🌐 Browser Compatibility

Q: Which browsers are supported?

A: Full support:

  • Chrome 113+: Best performance and features
  • Edge 113+: Excellent compatibility
  • Firefox 100+: Good support (no voice input)
  • Safari 16+: Limited support, may have issues

Q: Why doesn't it work in my browser?

A: Common issues:

  1. Outdated browser: Update to latest version
  2. JavaScript disabled: Enable JavaScript
  3. Privacy settings: Allow site permissions
  4. Extensions: Disable ad blockers temporarily
  5. Corporate firewall: May block local connections

Q: Mobile browser support?

A: Limited support:

  • iOS Safari: Basic functionality, no voice input
  • Android Chrome: Works but limited by mobile constraints
  • Recommendation: Use desktop for best experience
  • PWA: Future enhancement planned

🎤 Voice Input Issues

Q: Voice input shows "not supported"

A: Browser compatibility:

  • Chrome/Edge: Full support
  • Safari: Limited support, requires HTTPS
  • Firefox: Not supported (use text input)
  • Mobile: Limited support

Q: Microphone permission denied

A: Solutions:

  1. Check permissions: Browser settings → Site permissions → Microphone
  2. Allow access: Click "Allow" when prompted
  3. Refresh page: Try again after allowing
  4. Use HTTPS: Some browsers require secure connection
  5. Try different browser: Chrome/Edge work best

Q: Voice recognition is inaccurate

A: Tips for better accuracy:

  1. Speak clearly: Enunciate words properly
  2. Reduce background noise: Use quiet environment
  3. Speak at normal pace: Not too fast or slow
  4. Use good microphone: Better hardware = better results
  5. Check language settings: Ensure English is selected

🔒 Privacy & Security

Q: How do I verify privacy?

A: Privacy verification steps:

  1. Network tab: F12 → Network → Check for zero outgoing requests
  2. Airplane mode: Enable and test functionality
  3. Storage inspection: F12 → Application → Check IndexedDB
  4. Mode indicators: Header shows privacy status

Q: How do I delete all my data?

A: Data deletion methods:

  1. App reset: Click Clarity logo → Confirm reset
  2. Browser clear: Settings → Privacy → Clear browsing data
  3. Storage clear: F12 → Application → Clear IndexedDB and localStorage
  4. Manual delete: Export data first if needed

Q: Is my data really private?

A: Privacy guarantees:

  • Local Model Mode: 100% private, no data leaves device
  • Ollama Mode: 100% private, local processing
  • Demo Mode: ⚠️ Data sent to OpenRouter (clearly marked)
  • Verifiable: Check Network tab for confirmation

Q: What data is stored locally?

A: Local storage includes:

  • Model files: Gemma 3n models (.gguf files)
  • Conversations: Chat history and responses
  • Settings: App preferences and configuration
  • No personal data: No names, emails, or identifiers

⚡ Performance Issues

Q: App is slow or unresponsive

A: Performance optimization:

  1. Close other tabs: Free up memory
  2. Use smaller model: E2B instead of E4B
  3. Clear browser cache: Remove old data
  4. Restart browser: Fresh start
  5. Check system resources: Monitor RAM and CPU

Q: Model import takes too long

A: Import optimization:

  1. Use faster internet: For initial download
  2. Close other apps: Free up system resources
  3. Use SSD storage: Faster file operations
  4. Try smaller model: E2B downloads faster
  5. Check progress: Monitor import progress bar

Q: Responses are slow

A: Response time optimization:

  1. Use Ollama mode: Better performance than browser inference
  2. Close other applications: Free up RAM
  3. Use smaller model: E2B responds faster
  4. Check system resources: Monitor CPU usage
  5. Restart server: If using Ollama mode

🔧 Ollama-Specific Issues

Q: Ollama connection fails

A: Connection troubleshooting:

  1. Check server: Ensure ollama serve is running
  2. Verify port: Default is 11434
  3. Test manually: curl http://localhost:11434/api/tags
  4. Check firewall: Allow port 11434
  5. Restart Ollama: Kill and restart server

Q: "Model not found" in Ollama

A: Model troubleshooting:

  1. List models: ollama list
  2. Pull model: ollama pull gemma3n:e4b
  3. Check name: Use exact model name in Clarity
  4. Verify download: ollama show gemma3n:e4b
  5. Restart server: After pulling new model

Q: Ollama uses too much RAM

A: Memory optimization:

  1. Use smaller model: E2B uses less RAM
  2. Close other apps: Free up system memory
  3. Restart periodically: Clear memory cache
  4. Monitor usage: Use system monitor
  5. Upgrade RAM: Consider hardware upgrade

🎯 Competition & Demo

Q: How do I demonstrate Clarity to judges?

A: Demo preparation:

  1. Choose mode: Demo mode for quick setup
  2. Prepare examples: Have sample conversations ready
  3. Show privacy: Demonstrate Network tab verification
  4. Highlight features: Voice input, history, export
  5. Test beforehand: Ensure everything works

Q: What makes Clarity unique?

A: Key differentiators:

  1. Privacy-first: Only 100% offline AI assistant
  2. Multiple modes: Demo, Ollama, and local model options
  3. Accessibility: Works on low-end devices
  4. Transparency: Verifiable privacy guarantees
  5. Universal access: No cloud dependencies

Q: How do I verify competition compliance?

A: Compliance checklist:

  • Gemma 3n-only: No other models used
  • Privacy verified: Network tab shows zero requests
  • Documentation complete: All guides available
  • Code quality: Clean, maintainable code
  • User experience: Intuitive interface

📞 Support & Contact

Q: Where can I get help?

A: Support resources:

  1. Documentation: Check docs/ folder for guides
  2. Troubleshooting: See docs/TROUBLESHOOTING.md
  3. GitHub Issues: Report bugs and feature requests
  4. Community: Join discussions and get help
  5. Email: Contact for direct support

Q: How do I report a bug?

A: Bug reporting:

  1. Check existing issues: Search GitHub issues first
  2. Include details: Browser, OS, steps to reproduce
  3. Add screenshots: Visual evidence helps
  4. Console logs: F12 → Console → Copy errors
  5. System info: Include hardware and software details

Q: Can I contribute to Clarity?

A: Contribution welcome:

  1. Fork repository: Create your own copy
  2. Make changes: Follow coding standards
  3. Test thoroughly: Ensure privacy compliance
  4. Submit PR: Pull request with description
  5. Join community: Participate in discussions

🔮 Future Features

Q: What features are planned?

A: Upcoming enhancements:

  • PWA Support: Install as app
  • Mobile Optimization: Better mobile experience
  • Advanced Voice: Real-time transcription
  • Model Switching: Multiple model support
  • Export Formats: More export options

Q: Will there be a mobile app?

A: Mobile development:

  • PWA First: Progressive Web App approach
  • Native App: Future consideration
  • Current Focus: Desktop optimization
  • Mobile Web: Responsive design improvements

Q: Can I use other models?

A: Model support:

  • Current: Gemma 3n only (competition requirement)
  • Future: May support other models
  • Optimization: Clarity optimized for Gemma 3n
  • Testing: Other models not tested

FAQ Status: ✅ Comprehensive Coverage
Last Updated: 2024-01-XX
Support Level: ✅ Active Support Available