Hugging Face's logo

Spaces:
Prog-amin
/
pdf-qa-chatbot
Runtime error

App Files Community
pdf-qa-chatbot / backend /README.md
Amin23's picture
Amin23
Initial commit
e86a49a
preview code
|
raw
history blame contribute delete
5.58 kB

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

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 

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:
    pip install -r requirements.txt
  3. Copy .env.example to .env and fill in your API keys:
    cp .env.example .env
# Edit .env and set your keys
  4. Run the backend:
    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