🧠 AI-Powered Document API

Upload PDFs. Ask questions. Get AI-generated answers grounded in your documents.

---

📌 Overview

AI-Powered Document API is a full-stack application that enables users to upload PDF documents, automatically extract and index their content, and then ask natural-language questions that are answered by an AI — with responses grounded exclusively in the uploaded document's content.

Key Capabilities

Feature	Description
PDF Upload & Storage	Upload PDFs that are stored on Cloudinary with metadata persisted in PostgreSQL
Text Extraction	Automatic text extraction from uploaded PDFs using pypdf
Semantic Chunking	Documents are split into overlapping chunks for optimal retrieval
Vector Embeddings	Chunks are embedded using sentence-transformers/all-MiniLM-L6-v2
FAISS Indexing	Embeddings are indexed with Facebook AI Similarity Search for fast retrieval
AI Q&A	Users ask questions and receive answers generated by OpenAI gpt-4o-mini, grounded in retrieved document chunks
Auth System	JWT-based authentication with bcrypt password hashing
Response Caching	In-memory cache to avoid redundant AI calls for repeated queries
3D Animated UI	Immersive React frontend with Three.js 3D backgrounds and Framer Motion animations

---

🏗️ Architecture

┌────────────────────────────────────────────────────────────────────┐
│                         React Frontend                             │
│   Landing Page → Login/Register → Dashboard (Upload + Ask AI)      │
│   Three.js 3D Background · Framer Motion Animations                │
└─────────────────────────────┬──────────────────────────────────────┘
                              │ HTTPS (REST API)
                              ▼
┌────────────────────────────────────────────────────────────────────┐
│                       FastAPI Backend                               │
│                                                                     │
│  ┌──────────┐   ┌──────────────┐   ┌─────────────────────────┐     │
│  │ Auth API │   │ Document API │   │       AI Query API       │     │
│  │ /auth/*  │   │  /docs/*     │   │       /ai/ask            │     │
│  └────┬─────┘   └──────┬───────┘   └──────────┬──────────────┘     │
│       │                │                       │                    │
│       ▼                ▼                       ▼                    │
│  ┌─────────┐   ┌──────────────┐   ┌────────────────────────┐       │
│  │  JWT +  │   │  Cloudinary  │   │  FAISS Vector Search   │       │
│  │ bcrypt  │   │  + pypdf     │   │  + OpenAI gpt-4o-mini  │       │
│  └─────────┘   └──────────────┘   └────────────────────────┘       │
│                                                                     │
│              PostgreSQL (Users + Document Metadata)                 │
└────────────────────────────────────────────────────────────────────┘

Document Processing Pipeline

PDF Upload → Save Locally → Upload to Cloudinary → Extract Text (pypdf)
          → Chunk Text (500 chars, 50 overlap) → Generate Embeddings
          → Store in FAISS Index → Save Metadata to PostgreSQL

AI Query Pipeline

User Question → Check Cache → Embed Query → FAISS Similarity Search
             → Retrieve Top-5 Chunks → Send to OpenAI with Context
             → Cache & Return Answer

---

🛠️ Tech Stack

Backend

Technology	Purpose
FastAPI	High-performance async web framework
SQLAlchemy	ORM for PostgreSQL
psycopg2-binary	PostgreSQL adapter
python-jose	JWT token encoding/decoding
passlib + bcrypt	Secure password hashing
pypdf	PDF text extraction
sentence-transformers	Text embeddings (all-MiniLM-L6-v2)
FAISS (faiss-cpu)	Vector similarity search
OpenAI Python SDK	GPT-4o-mini for answer generation
Cloudinary	Cloud-based file storage for uploaded PDFs
python-dotenv	Environment variable management

Frontend

Technology	Purpose
React 19	UI library
Vite	Build tool and dev server
React Router v7	Client-side routing
Framer Motion	Page transitions and micro-animations
Three.js + @react-three/fiber	3D animated backgrounds
Lucide React	Icon library
Axios	HTTP client

---

🚀 Getting Started

Prerequisites

• Python 3.10+
• Node.js 18+
• PostgreSQL database (local or hosted)
• Cloudinary account (sign up free)
• OpenAI API key (get one here)

1. Clone the Repository

git clone https://github.com/Maherimtiyaz/AI_Powered_Doc_API.git
cd AI-Powered-Doc-API

2. Backend Setup

# Create and activate virtual environment
python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Configure Environment Variables

Copy the example file and fill in your values:

cp .env.example .env

Edit .env with your credentials:

DATABASE_URL=postgresql://user:password@localhost:5432/doc_ai_db
SECRET_KEY=your-super-secret-key
ALGORITHM=HS256

OPENAI_API_KEY=sk-...your-openai-key

CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

FRONTEND_URL=http://localhost:5173
FAISS_BASE_PATH=faiss_indexes

4. Run the Backend

uvicorn app.main:app --reload --port 8000

The API will be live at http://localhost:8000. Visit http://localhost:8000/docs for interactive Swagger documentation.

5. Frontend Setup

cd frontend
npm install
npm run dev

The frontend will be live at http://localhost:5173.

---

📡 API Reference

Health Check

Method	Endpoint	Description
GET	/	Returns {"message": "API is running"}

Authentication — /auth

Method	Endpoint	Parameters	Description
POST	/auth/register	email, password (query)	Register a new user
POST	/auth/login	email, password (query)	Login and receive a JWT access_token

Documents — /docs

Method	Endpoint	Headers	Body	Description
POST	/docs/upload	token (query param)	file (multipart PDF)	Upload and process a PDF document

Response:

{
  "file_id": "uuid-string",
  "filename": "report.pdf",
  "cloudinary_url": "https://res.cloudinary.com/...",
  "chunks": 42,
  "message": "Document processed successfully"
}

AI Query — /ai

Method	Endpoint	Body (JSON)	Description
POST	/ai/ask	{"query": "...", "file_id": "..."}	Ask a question about a specific document

Response:

{
  "answer": "Based on the document, ...",
  "chunks_used": 5,
  "source": "generated"
}

Cached responses return "source": "cache" instead.

---

📂 Project Structure

AI-Powered-Doc-API/
├── app/
│   ├── main.py                  # FastAPI entry point, CORS, route registration
│   ├── __init__.py
│   ├── api/
│   │   ├── auth_routes.py       # /auth/register, /auth/login
│   │   ├── document_auth.py     # /docs/upload (authenticated)
│   │   ├── ai_routes.py         # /ai/ask
│   │   └── deps.py              # Shared dependencies (get_db, get_current_user)
│   ├── core/
│   │   ├── config.py            # Environment variable loading
│   │   ├── database.py          # SQLAlchemy engine, session, Base
│   │   ├── security.py          # JWT creation, password hashing
│   │   ├── cache.py             # In-memory query cache
│   │   └── rate_limiter.py      # Rate limiting (placeholder)
│   ├── models/
│   │   ├── user.py              # User SQLAlchemy model
│   │   └── document.py          # Document SQLAlchemy model
│   ├── schemas/
│   │   ├── user_schema.py       # Pydantic schemas for auth
│   │   └── document_schema.py   # Pydantic schemas for documents
│   ├── services/
│   │   ├── auth_service.py      # Registration & login business logic
│   │   ├── ai_service.py        # RAG pipeline: retrieve chunks → generate answer
│   │   └── document_service.py  # Full document processing pipeline
│   └── utils/
│       ├── chunking.py          # Text chunking with overlap
│       ├── embeddings.py        # Sentence-transformer embeddings
│       ├── faiss_store.py       # FAISS index read/write
│       └── cloudinary_helper.py # Cloudinary upload helper
├── tests/
│   ├── conftest.py              # Test fixtures (SQLite test DB, test client)
│   ├── test_auth.py             # Auth endpoint tests
│   ├── test_docs.py             # Document upload tests
│   └── test_ai.py               # AI query tests
├── frontend/
│   ├── src/
│   │   ├── App.jsx              # Router, AnimatePresence, 3D scene
│   │   ├── main.jsx             # React entry point
│   │   ├── index.css            # Global styles & design system
│   │   ├── components/
│   │   │   └── Scene3D.jsx      # Three.js animated 3D background
│   │   └── pages/
│   │       ├── Landing.jsx      # Hero landing page
│   │       ├── Login.jsx        # Login / Register form
│   │       └── Dashboard.jsx    # Upload PDFs + Ask AI interface
│   ├── package.json
│   └── vite.config.js
├── docker/
│   ├── Dockerfile               # Docker image definition
│   └── docker-compose.yml       # Docker Compose configuration
├── .github/
│   └── workflows/
│       └── ci.yml               # GitHub Actions CI pipeline
├── .env.example                 # Template for environment variables
├── .gitignore
├── render.yaml                  # Render Blueprint (backend + frontend + DB)
├── requirements.txt             # Pinned Python dependencies
└── README.md

---

☁️ Deployment on Render

This project includes a render.yaml Blueprint for one-click deployment.

Render Services Created

Service	Type	Runtime	Description
doc-ai-db	PostgreSQL	—	Free-tier managed database
doc-ai-backend	Web Service	Python	FastAPI backend on port 10000
doc-ai-frontend	Static Site	Node	Vite-built React SPA

Steps

1. Push to GitHub — Ensure all changes are committed and pushed.

2. Create Blueprint on Render

   • Go to Render Dashboard → New → Blueprint
   • Connect your GitHub repository
   • Render auto-detects render.yaml

3. Set Manual Environment Variables These variables are marked sync: false in render.yaml and must be set manually in the Render dashboard:

   Variable	Where to Get It
   OPENAI_API_KEY	OpenAI API Keys
   CLOUDINARY_CLOUD_NAME	Cloudinary Console
   CLOUDINARY_API_KEY	Cloudinary Console → Settings
   CLOUDINARY_API_SECRET	Cloudinary Console → Settings

4. Deploy — Render builds and deploys both services automatically.

Auto-Configured Variables

These are handled by render.yaml automatically:

• DATABASE_URL — Injected from the managed PostgreSQL instance
• SECRET_KEY — Auto-generated secure random value
• ALGORITHM — Set to HS256
• FRONTEND_URL — Injected from the static site URL
• VITE_API_URL — Injected into the frontend from the backend URL
• PYTHON_VERSION — Set to 3.10.0

⚠️ Important Notes

• Ephemeral Filesystem: Render's free tier has an ephemeral disk. FAISS indexes stored locally will be lost on every deploy or restart. For persistent vector storage, consider upgrading to a paid tier with a persistent disk or migrating to a managed vector database (e.g., Pinecone, Weaviate).
• Cold Starts: Free-tier web services spin down after 15 minutes of inactivity. The first request after a cold start may take 30–60 seconds as the sentence-transformers model loads into memory.

---

🧪 Running Tests

# Activate virtual environment
venv\Scripts\activate  # Windows
source venv/bin/activate  # macOS / Linux

# Run all tests
PYTHONPATH=. python -m pytest tests/ -v

Tests use an in-memory SQLite database and mock external services, so no external credentials are needed.

---

🔧 Environment Variables Reference

Variable	Required	Description	Default
DATABASE_URL	✅	PostgreSQL connection string	—
SECRET_KEY	✅	JWT signing secret	change-me-in-production
ALGORITHM	✅	JWT algorithm	HS256
OPENAI_API_KEY	✅	OpenAI API key for answer generation	—
CLOUDINARY_CLOUD_NAME	✅	Cloudinary cloud name	—
CLOUDINARY_API_KEY	✅	Cloudinary API key	—
CLOUDINARY_API_SECRET	✅	Cloudinary API secret	—
FRONTEND_URL	⬜	Frontend URL for CORS	""
FAISS_BASE_PATH	⬜	Directory for FAISS indexes	faiss_indexes

---

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📜 License

This project is open source and available under the MIT License.

---

Built with ❤️ using FastAPI, React, and OpenAI