Spaces:
Sleeping
Sleeping
File size: 5,458 Bytes
1bea311 dd0e06c fdb6191 6380c1d 2c79106 fdb6191 d346ae0 fdb6191 93b7744 d346ae0 fdb6191 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 |
---
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.
---
|