HackNexus AI Document Assistant - Backend

Production-ready FastAPI backend for document Q&A using RAG (Retrieval-Augmented Generation) with Gemini AI.

Features

• 📄 Document Upload: PDF and DOCX support with validation
• 🔍 Semantic Search: FAISS vector database for fast similarity search
• 🤖 AI-Powered Q&A: Gemini 2.5 Flash for accurate, grounded answers
• 🎯 Source Citations: Returns page numbers and snippets
• 🔒 Error Handling: Comprehensive validation and error responses
• 🌐 CORS Enabled: Ready for frontend integration

Tech Stack

• Framework: FastAPI + Uvicorn
• AI: Google Gemini 2.0 Flash (via google-genai SDK)
• Vector DB: FAISS for embedding storage
• Embeddings: Sentence Transformers (all-MiniLM-L6-v2)
• Document Parsing: PyPDF2, python-docx

Setup Instructions

1. Install Dependencies

cd backend
pip install -r requirements.txt

2. Configure Environment

Create a .env file in the backend directory:

GEMINI_API_KEY=your_gemini_api_key_here

Get your API key from: https://aistudio.google.com/apikey

3. Run the Server

uvicorn app.main:app --reload --env-file .env

The API will be available at: http://localhost:8000

API Endpoints

Health Check

GET /

Response:

{
  "status": "Backend running successfully",
  "team": "HackNexus",
  "service": "AI Document Assistant"
}

Upload Document

POST /upload/
Content-Type: multipart/form-data

Request:

• file: PDF or DOCX file (max 20MB)

Response:

{
  "message": "Document uploaded and indexed successfully",
  "total_chunks": 42
}

Ask Question

POST /query/
Content-Type: application/json

Request:

{
  "question": "What is the refund policy?"
}

Response:

{
  "answer": "Customers can request a refund within 30 days of purchase.",
  "confidence": 0.82,
  "sources": [
    {
      "page": 3,
      "snippet": "Refunds accepted within 30 days of purchase..."
    }
  ]
}

Project Structure

backend/
├── app/
│   ├── main.py              # FastAPI app with CORS
│   ├── config.py            # Environment & settings
│   ├── models/
│   │   └── schemas.py       # Pydantic models
│   ├── routes/
│   │   ├── upload.py        # Document upload endpoint
│   │   └── query.py         # Q&A endpoint
│   ├── services/
│   │   ├── document_loader.py   # PDF/DOCX parsing
│   │   ├── vector_store.py      # FAISS operations
│   │   └── qa_engine.py         # Gemini RAG pipeline
│   └── utils/
│       └── references.py    # Helper functions
├── data/
│   ├── uploads/             # Temporary file storage
│   └── vector_db/           # FAISS index storage
├── .env                     # Environment variables
├── requirements.txt         # Python dependencies
└── README.md               # This file

Key Features Explained

1. CORS Configuration

• Allows frontend connections from multiple origins
• Handles preflight requests
• Returns proper headers even on errors

2. Document Processing

• Validates file types and sizes
• Extracts text page-by-page
• Creates overlapping chunks for better context

3. Vector Storage

• Generates 384-dim embeddings
• Stores in FAISS for fast retrieval
• Persists to disk automatically

4. RAG Pipeline

1. Question → Embedding
2. Similarity search → Top 3 chunks
3. Build context with page numbers
4. Gemini generates grounded answer
5. Return with confidence & sources

Troubleshooting

CORS Errors

Make sure your frontend URL is listed in main.py CORS middleware.

Gemini API Errors

• Check your API key in .env
• Verify internet connection
• Check quota limits at Google AI Studio

Upload Fails

• Check file size (<20MB)
• Verify file extension (.pdf or .docx)
• Check backend logs for errors

No Documents Found

• Upload a document first
• Check if FAISS index was created in data/vector_db/

Environment Variables

Variable	Required	Description
GEMINI_API_KEY	✅ Yes	Google Gemini API key

Development

Run in Debug Mode

uvicorn app.main:app --reload --env-file .env --log-level debug

View Logs

All operations print to console with emoji indicators:

• ✅ Success
• ❌ Error
• ⚠️ Warning
• 🔄 Processing
• 📦 Loading

Production Deployment

For production, consider:

1. Use proper secrets management
2. Add authentication
3. Implement rate limiting
4. Add request logging
5. Use PostgreSQL for metadata
6. Deploy with Docker

License

MIT