Hugging Face's logo

Spaces:
umar-100
/
smart-research-assistant
Sleeping

App Files Community
smart-research-assistant / README.md
umar-100's picture
umar-100
included loom link
6380c1d
preview code
|
raw
history blame contribute delete
5.46 kB
metadata
title: Smart Research Assistant
emoji: 👁
colorFrom: yellow
colorTo: red
sdk: docker
pinned: false

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Smart Research Assistant

A document-aware AI assistant for research summarization, question-answering, and logic-based question generation, built with FastAPI (backend) and Streamlit (frontend), deployed as a single Docker container.

Huggingface spaces link: https://huggingface.co/spaces/umar-100/smart-research-assistant

Loom demo link: https://www.loom.com/share/0a5302faa01e422394cda7a760c172f6?sid=b60a82e0-796b-416d-bc28-bad526a60fc5

Features

  • Document Upload: Upload PDF or TXT documents for processing.
  • Auto Summary: Generate concise (≤150 words) summaries of uploaded documents.
  • Ask Anything: Ask free-form questions and receive answers grounded in the uploaded document.
  • Challenge Me: Generate three logic-based or comprehension-focused questions from the document.
  • Evaluate Responses: Evaluate user answers to logic-based questions with feedback and justification.
  • Session Management: Each user session is tracked for document and interaction history.
  • Vector Database Integration: Uses Pinecone for semantic search and retrieval.
  • Clean UI: Intuitive web interface for uploading, querying, and interacting with documents.

Architecture

  • Backend: FastAPI (Python)
    • Handles document upload, storage, and retrieval.
    • Implements endpoints for Q&A, question generation, and answer evaluation.
    • Uses SQLite for session/document management and Pinecone for vector search.
  • Frontend: Streamlit (Python)
    • Provides a web interface for users to upload documents, ask questions, and receive feedback.
    • Communicates with the backend via HTTP requests.
  • Vector Database: Pinecone
    • Stores document embeddings for semantic search and retrieval.
  • Deployment: Single Docker container with both backend and frontend services.
    • FastAPI runs on port 8000 (internal).
    • Streamlit runs on port 7860 (exposed to users).
    • No Nginx or reverse proxy required for minimal setup.

Setup

Requirements

  • Docker
  • Pinecone API key (for vector search)
  • OpenAI API key (for LLM inference)

1. Clone the Repository 

git clone https://github.com/m-umar-j/smart-research-assistant.git
cd smart-research-assistant

2. Environment Variables

Create a .env file in the project root with the following variables:

OPENAI_API_KEY=your_openai_key
PINECONE_API_KEY=your_pinecone_key

3. Build and Run with Docker

docker build -t smart-research-assistant . docker run -p 7860:7860 --env-file .env smart-research-assistant

  • Port 7860 is exposed for Streamlit.
  • Port 8000 is used internally for FastAPI.

4. Access the Application

Open your browser to:

http://localhost:7860

Commands

  • Start Streamlit and FastAPI (via start.sh):
cd /app && uvicorn backend.main:app --host 0.0.0.0 --port 8000 &
cd /app && streamlit run frontend/app.py --server.port=7860 --server.address=0.0.0.0 --browser.gatherUsageStats=false --server.enableXsrfProtection=false

Technical Details

Backend

  • FastAPI endpoints:
  • /upload-doc: Upload and index documents (PDF/TXT).
  • /list-docs: List documents by session.
  • /chat: Answer questions based on uploaded documents.
  • /challenge-me: Generate logic-based questions.
  • /evaluate-response: Evaluate user answers to logic-based questions.
  • Database: SQLite (research_assistant.db) for session/document storage.
  • Vector Database: Pinecone for document embeddings and semantic retrieval.

Frontend

  • Streamlit UI:
  • Upload documents.
  • Display summaries.
  • Ask questions and view answers.
  • Generate and answer logic-based questions.
  • View feedback on answers.

Data Flow

  1. User uploads a document.
  2. Document is split, embedded, and indexed in Pinecone.
  3. User asks questions or requests logic-based questions.
  4. Backend retrieves relevant document chunks and generates answers/feedback.
  5. Frontend displays results to the user.

Known Issues & Workarounds

  • File uploads on Hugging Face Spaces:
  • Disable XSRF protection in Streamlit (--server.enableXsrfProtection=false).
  • File uploads may still be restricted by platform security policies.
  • Database permissions:
  • Ensure /app is writable in Docker (handled by chmod -R 777 /app in Dockerfile).
  • Pinecone indexing:
  • Ensure Pinecone index exists and API key is valid.

Folder Structure 

smart-research-assistant/
├── backend/           # FastAPI backend code
│   └── ...            
├── frontend/          # Streamlit frontend code
│   └── ...            
├── .env               # Environment variables
├── requirements.txt   # Python dependencies
├── Dockerfile         # Docker build file
├── start.sh           # Startup script
└── README.md          # This file

Additional Notes

  • Session management: Each user session is tracked with a unique ID.
  • Vector search: Chunks of uploaded documents are embedded and indexed in Pinecone for semantic retrieval.
  • LLM integration: Uses OpenAI's GPT-4 for question-answering and feedback generation.