---
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.

---