Spaces:
Runtime error
Runtime error
File size: 5,577 Bytes
e86a49a |
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 |
# PDF Q&A Chatbot Backend
A FastAPI backend for a PDF-based Q&A chatbot. Upload PDF documents, ask questions, and get answers based on document content using LLMs (OpenRouter, Anthropic, etc.).
---
## Table of Contents
- [Overview](#overview)
- [Architecture](#architecture)
- [Features](#features)
- [API Endpoints](#api-endpoints)
- [Quick Start](#quick-start)
- [Environment Variables (`.env`)](#environment-variables-env)
- [File Structure](#file-structure)
- [Security Notes](#security-notes)
- [Hugging Face Spaces Deployment](#hugging-face-spaces-deployment)
- [Troubleshooting](#troubleshooting)
- [Contribution](#contribution)
- [License](#license)
---
## Overview
This backend enables a chatbot to answer questions based on the content of uploaded PDF documents. It uses vector search (ChromaDB) to find relevant document chunks and LLMs (OpenRouter, Anthropic) to generate answers. All data is erased on backend restart (demo mode).
---
## Architecture
```mermaid
graph TD;
User["User (Frontend)"] -->|Uploads PDF, Asks Question| API["FastAPI Backend"]
API -->|Stores| DB[("SQLite DB")]
API -->|Stores/Queries| ChromaDB["ChromaDB Vector Store"]
API -->|Calls| LLM["LLM API (OpenRouter/Anthropic)"]
API -->|Serves| User
```
---
## Features
- **Upload up to 3 PDF documents** (demo limit, can be changed)
- **Ask questions** and get AI-generated answers based on your PDFs
- **Vector search**: Finds the most relevant document chunks for each question
- **LLM integration**: Uses OpenRouter (OpenAI-compatible) or Anthropic Claude
- **All data erased on restart**: Ensures stateless demo for reviewers
- **Admin endpoint** to clear all data manually
- **API health check** endpoint
---
## API Endpoints
### Document Management
- `POST /api/v1/documents/upload` — Upload a PDF (max 3, 10MB each)
- `GET /api/v1/documents/` — List all uploaded documents
- `GET /api/v1/documents/{document_id}` — Get a specific document
- `DELETE /api/v1/documents/{document_id}` — Delete a document
- `POST /api/v1/documents/clear_all` — Clear all documents, chat, uploads, and vectors (admin)
- `GET /api/v1/documents/stats/summary` — Get document and vector store stats
### Chat
- `POST /api/v1/chat/` — Ask a question (with session ID, model, and optional document ID)
- `GET /api/v1/chat/history/{session_id}` — Get chat history for a session
- `POST /api/v1/chat/session/new` — Create a new chat session
- `GET /api/v1/chat/sessions` — List all chat sessions
- `DELETE /api/v1/chat/session/{session_id}` — Delete a chat session
- `GET /api/v1/chat/models/available` — List available LLM models
### Health
- `GET /health` — Health check
- `GET /` — API info
---
## Quick Start
1. **Clone the repo**
2. **Install dependencies:**
```bash
pip install -r requirements.txt
```
3. **Copy `.env.example` to `.env` and fill in your API keys:**
```bash
cp .env.example .env
# Edit .env and set your keys
```
4. **Run the backend:**
```bash
uvicorn main:app --host 0.0.0.0 --port 8000
```
---
## Environment Variables (`.env`)
- **Never commit your real `.env` file to version control!**
- Example variables:
- `SECRET_KEY` — Generate with `python -c "import secrets; print(secrets.token_urlsafe(64))"`
- `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` — Set your API keys here
- `DATABASE_URL` — Default is SQLite, can be set to PostgreSQL for production
- `UPLOAD_DIR`, `CHROMA_PERSIST_DIRECTORY` — Directories for uploads and vector store
- See `.env.example` for all options
---
## File Structure
```
backend/
app/
api/endpoints/ # FastAPI route handlers
core/ # Config, DB setup
models/ # SQLAlchemy models
schemas/ # Pydantic schemas
services/ # PDF, AI, vector store logic
chroma_db/ # ChromaDB vector store (excluded by .gitignore)
uploads/ # Uploaded PDFs (excluded by .gitignore)
requirements.txt # Python dependencies
main.py # FastAPI app entrypoint
.env.example # Example environment file
.gitignore # Excludes sensitive/data files
README.md # This file
```
---
## Security Notes
- **Never commit real API keys or secrets to your repo.**
- The `SECRET_KEY` should be a long, random string (see above).
- For real deployments, remove the auto-wipe logic and use a persistent database.
- Validate all uploaded files (PDF only, max 10MB).
- CORS is restricted to localhost by default; update for production.
---
## Hugging Face Spaces Deployment
- Set all secrets (API keys, secret key) using the Spaces UI, not in `.env`.
- The backend will erase all data on restart (stateless demo mode).
- SQLite is used for demo purposes; for production, use PostgreSQL.
- Spaces may restart your app at any time; do not rely on local persistence.
---
## Troubleshooting
- **API key issues:** Ensure your keys are set in the environment or Spaces UI.
- **Vector store empty:** Check logs for ChromaDB errors; ensure singleton pattern is used.
- **Uploads not working:** Check file size/type and that `uploads/` exists and is writable.
- **CORS errors:** Update `BACKEND_CORS_ORIGINS` in `.env` or config.
- **App restarts:** All data is wiped on restart by design (demo mode).
---
## Contribution
1. Fork the repo and create a feature branch.
2. Make your changes (ensure code is clean and tested).
3. Submit a pull request with a clear description.
4. For major changes, open an issue first to discuss.
---
## License
MIT |