Smart FAQ Assistant

AI-powered FAQ search system using Cosdata OSS vector database - Built for Cosdata Hackathon 2025

🎯 Project Overview

Smart FAQ Assistant helps small businesses automate customer support by providing semantic search capabilities over their FAQ database. Instead of keyword matching, it uses vector similarity search powered by Cosdata OSS to understand the meaning of customer questions.

✨ Features

• 📝 Easy FAQ Management - Add individual FAQs or bulk upload
• 🔍 Semantic Search - Search by meaning, not just keywords
• 🎨 Modern UI - Clean, responsive React interface
• ⚡ Fast Performance - Powered by Cosdata OSS vector search
• 📊 Categorization - Organize FAQs by category (General, Technical, Billing, Product)
• 🎯 Similarity Scores - See how well each result matches your query

🏗️ Tech Stack

Frontend:

• React 18
• Vite
• CSS3

Backend:

• Node.js
• Express.js
• Cosdata OSS (Vector Database)

📋 Prerequisites

• Node.js (v18 or higher)
• npm or yarn
• Docker Desktop (for running Cosdata)
• Windows PowerShell

🚀 Quick Start

1. Set Up Cosdata OSS with Docker

Pull and Run Cosdata:

# Pull the image
docker pull cosdataio/cosdata:latest

# Run the container
docker run -d --name cosdata-server -p 8443:8443 -p 50051:50051 cosdataio/cosdata:latest


# Verify it's running
docker ps

# NOTE: This Cosdata image may not expose /health (it can return 404).
# Instead, create a session and then call an authenticated endpoint.
curl -sS -X POST http://localhost:8443/auth/create-session \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":""}'

✅ You should see a JSON response containing an access_token.

📖 Detailed setup: See COSDATA_SETUP.md

2. Install Dependencies

# Install backend dependencies
cd backend
npm install

# Frontend already has dependencies installed

3. Configure Environment

The .env file is already created with default settings:

PORT=5050
COSDATA_API_URL=http://localhost:8443

If needed, you can also set Cosdata credentials (local Docker commonly uses an empty admin key):

COSDATA_USERNAME=admin
COSDATA_PASSWORD=

Optional: Add Hugging Face API key for better rate limits (free):

HUGGINGFACE_API_KEY=your_key_from_https://huggingface.co/settings/tokens

4. Run the Application

Terminal 1 - Backend:

cd backend
npm run dev
# Server runs on http://localhost:5050

Terminal 2 - Frontend:

cd frontend
npm run dev
# App runs on http://localhost:5173

5. Try It Out! 🎉

1. Open http://localhost:5173 in your browser
2. Click "Load Sample FAQs" to add demo data (5 FAQs)
3. Try semantic search:
   • "How do I get my money back?" → Finds refund policy
   • "Can't login" → Finds password reset
   • "When are you open?" → Finds business hours
4. Watch semantic search in action - it understands meaning, not just keywords!

📁 Project Structure

smart-faq-assistant/
├── backend/
│   ├── routes/
│   │   ├── faqRoutes.js      # FAQ CRUD endpoints
│   │   └── searchRoutes.js   # Search endpoint
│   ├── services/
│   │   └── cosdataService.js # Cosdata integration
│   ├── server.js             # Express server
│   ├── package.json
│   └── .env
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── FAQUpload.jsx    # FAQ upload form
│   │   │   ├── SearchBox.jsx    # Search interface
│   │   │   └── ResultsList.jsx  # Search results
│   │   ├── App.jsx
│   │   └── App.css
│   └── package.json
└── README.md

🔌 API Endpoints

FAQ Management

• GET /api/faq - Get all FAQs
• POST /api/faq - Add single FAQ
• POST /api/faq/bulk - Bulk upload FAQs
• DELETE /api/faq/:id - Delete FAQ

Search

• POST /api/search - Semantic search

  {
    "query": "How do I reset my password?",
    "topK": 5
  }

🎓 How It Works

1. FAQ Upload: Questions and answers are converted to 384-dimensional vector embeddings using Hugging Face's BAAI/bge-small-en-v1.5 model (FREE!)
2. Vector Storage: Embeddings stored in Cosdata OSS vector database with metadata (answer, category, timestamp)
3. Semantic Search: User queries are converted to vectors and matched using cosine similarity in Cosdata
4. Ranked Results: Most relevant FAQs returned with similarity scores

Why It's Better Than Keyword Search:

• Understands "refund" = "money back" = "get my cash returned"
• Matches "can't sign in" with "reset password"
• No need for exact keyword matches!

🆓 Free Embeddings Setup

This project uses 100% FREE embedding generation:

Hugging Face Inference API (No credit card required!)

• Model: BAAI/bge-small-en-v1.5
• Dimensions: 384
• Rate Limit: ~1000 requests/hour without API key
• With free API key: Much higher limits

Get Your Free API Key (Optional but Recommended):

1. Sign up at https://huggingface.co (free)
2. Go to https://huggingface.co/settings/tokens
3. Create a new token (Read access is enough)
4. Add to backend/.env: HUGGINGFACE_API_KEY=your_token_here

🔧 Customization

Use Different Embedding Model

Edit backend/services/cosdataService.js:

// Change the model
this.embeddingModel = 'sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2'; // For multilingual support
// or
this.embeddingModel = 'BAAI/bge-small-en-v1.5'; // Higher quality, still free

// Update dimension if needed
this.dimension = 384; // or 768, 1024 depending on model

Add More FAQ Categories

Edit frontend/src/components/FAQUpload.jsx:

<select id="category" ...>
  <option value="general">General</option>
  <option value="technical">Technical</option>
  <option value="billing">Billing</option>
  <option value="product">Product</option>
  <option value="shipping">Shipping</option>  {/* Add your category */}
</select>

🚧 Next Steps / Improvements

• ✅ Integrate Cosdata OSS vector database
• ✅ Use free Hugging Face embeddings
• ✅ Semantic search functionality
• Add authentication for multi-business support
• Persist FAQs to PostgreSQL/MongoDB
• Add analytics dashboard (search trends, popular questions)
• Deploy to cloud (Vercel + Railway/Render)
• Add file upload for bulk FAQ import (CSV/JSON)
• Implement caching for faster searches
• Add multilingual support

🐛 Troubleshooting

Cosdata not running?

# Check if container is running
docker ps

# Check logs
docker logs cosdata-server

# Restart container
docker restart cosdata-server

Backend won't start?

• Check if port 5050 is available: netstat -an | findstr 5050
• Ensure Cosdata is running: curl http://localhost:8443/health
• Check backend logs for errors

Search returns empty results?

• Make sure you've added FAQs first (click "Load Sample FAQs")
• Check backend console for embedding errors
• Verify Cosdata connection in backend logs
• Try restarting backend server

Hugging Face rate limit errors?

• Get a free API key from https://huggingface.co/settings/tokens
• Add to backend/.env: HUGGINGFACE_API_KEY=your_token
• Restart backend server

Frontend shows connection error?

• Ensure backend is running on port 5050
• Check browser console for CORS errors
• Verify http://localhost:5050/health returns OK

🎯 Business Value

• Reduce Support Tickets: Customers find answers instantly
• 24/7 Availability: No human agent needed
• Scalable: Handles thousands of FAQs efficiently
• Cost Savings: Reduce support team workload by 60-70%

📝 License

MIT License - Built for Cosdata Hackathon 2025

🙏 Acknowledgments

• Cosdata for the amazing OSS vector database
• Vite for blazing fast development
• React for the UI framework

📧 Contact

Built by [Your Name] for Cosdata Hackathon 2025

---

⭐ Don't forget to star the Cosdata repo!