README.md

---
title: AuthorBot RAG
emoji: 📚
colorFrom: indigo
colorTo: purple
sdk: docker
pinned: false
app_port: 7860
storage: true
---

# AuthorBot RAG Chatbot SaaS
### Production-grade AI book advisor for author websites

[![HuggingFace](https://img.shields.io/badge/Hosted%20on-HuggingFace%20Spaces-orange)](https://huggingface.co/spaces)
[![Python](https://img.shields.io/badge/Python-3.11-blue)](https://python.org)
[![Next.js](https://img.shields.io/badge/Next.js-16-black)](https://nextjs.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Overview

AuthorBot is a multi-tenant SaaS platform that gives every author a personalized AI chatbot trained on their book documents. The chatbot answers reader questions, recommends books, and drives purchase conversions — with full guardrails, analytics, and a beautiful admin dashboard.

---

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                   Author Website                     │
│   <script src="cdn/widget.min.js">                   │
└──────────────────────┬──────────────────────────────┘
                       │ HTTP (subscription token)
┌──────────────────────▼──────────────────────────────┐
│             FastAPI Backend (HuggingFace)            │
│   12-step RAG pipeline · 5-layer security           │
│   GPT-4o · ChromaDB · Redis · PostgreSQL            │
└──────────────────────────────────────────────────────┘
        ▲                            ▲
        │ CRUD                       │ Admin
┌───────┴──────┐           ┌────────┴────────┐
│  Next.js     │           │  SuperAdmin     │
│  Dashboard   │           │  Dashboard      │
└──────────────┘           └─────────────────┘
```

---

## Features

### Admin Dashboard
| Feature | Details |
|---|---|
| **Overview** | KPI cards, token budget, book status |
| **Books** | Full CRUD, drag-to-reorder, AI summary |
| **Documents** | PDF/EPUB/DOCX/TXT upload, live SSE status |
| **Chatbot Config** | Live preview, 5 themes, auto-open delay |
| **Analytics** | Charts, donut budget, daily table |
| **Settings** | Profile, chatbot config, notification prefs |
| **Embed Code** | 3-step generator with copy button |

### SuperAdmin
| Feature | Details |
|---|---|
| **Grant Access** | Token generation (HMAC-SHA256), plan selection |
| **Revoke Access** | Instant Redis invalidation + reason required |
| **Extend/Bonus** | Extend expiry or add bonus token budget |
| **Audit Log** | Append-only, immutable, filterable |
| **TOTP 2FA** | QR code enrollment, time-based OTP |

### RAG Pipeline (12 Steps)
```
1. Boundary Check   → Reject jailbreaks (10 regex rules)
2. Intent Classify  → 8 intent types via GPT-4o sub-prompt
3. Session Resolve  → Book disambiguation, history load
4. Query Rewrite    → Pronoun resolution + 3 variations
5. Retrieve         → ChromaDB similarity search (top-20)
6. Re-rank          → CrossEncoder (ms-marco-MiniLM)
7. Context Build    → Token-budgeted (3800 tokens max)
8. LLM Generate     → GPT-4o with upsell-aware system prompt
9. Faithfulness     → NLI (DeBERTa) entailment check
10. Scope Leak      → Second boundary check post-generation
11. Upsell Inject   → 8-strategy engine (interest-based)
12. Format          → Links, markdown, session update
```

### Chat Widget
- Zero dependencies, ~8KB minified
- 5 themes: midnight, ocean, forest, sunset, minimal
- Book disambiguation popup
- Typing indicator, link click tracking
- `AuthorBot.open()` / `.close()` / `.toggle()` API

---

## Quick Start (Local Development)

### Prerequisites
- Docker & Docker Compose
- Node.js 18+
- OpenAI API Key
- MaxMind GeoLite2 License Key (free)

### 1. Clone and configure
```bash
git clone <your-repo>
cd "Author RAG/backend"
cp .env.example .env
# Fill in OPENAI_API_KEY, DATABASE_URL, etc.
```

### 2. Start all services
```bash
docker-compose up -d
```

### 3. Create SuperAdmin account
```bash
docker exec -it authorbot_api python -m app.scripts.create_superadmin \
  --email admin@yourcompany.com --password YourStrongPass123!
```

### 4. Start admin dashboard
```bash
cd ../frontend/admin
npm install
npm run dev
# Open http://localhost:3000
```

### 5. Test the widget
Open `frontend/widget/demo.html` in a browser.

---

## Deployment to HuggingFace Spaces

### 1. Create a new Space
- Go to huggingface.co/new-space
- Select **Docker** as the SDK
- Set `app_port: 8080`

### 2. Set Secret Environment Variables
In the Space Settings → Secrets, add:

| Secret | Description |
|---|---|
| `OPENAI_API_KEY` | Your OpenAI key |
| `DATABASE_URL` | PostgreSQL connection string (Supabase, Neon, or Railway) |
| `REDIS_URL` | Redis connection (Upstash or Railway) |
| `SECRET_KEY` | 64-char random string (JWT signing) |
| `SUBSCRIPTION_SECRET` | 32-char random string (token HMAC) |
| `SUPERADMIN_TOTP_SECRET` | 20-char base32 string |
| `GMAIL_USER` | Gmail address for notifications |
| `GMAIL_APP_PASSWORD` | Gmail App Password |
| `MAXMIND_LICENSE_KEY` | MaxMind GeoLite2 license key |

### 3. Push your code
```bash
# HuggingFace uses git for deployment
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/authorbot-api
git push hf main
```

> The Dockerfile handles: Alembic migrations → Uvicorn startup → health checks

### 4. Deploy admin dashboard (Vercel recommended)
```bash
cd frontend/admin
npx vercel --prod
# Set NEXT_PUBLIC_API_URL to your HF Space URL
```

### 5. Deploy the widget
Upload `frontend/widget/widget.js` to any CDN (Cloudflare Pages, Vercel, etc.) and serve as:
```
https://cdn.yourdomain.com/widget.min.js
```

---

## Environment Variables Reference

See [`backend/.env.example`](backend/.env.example) for the full list with comments.

Key variables:
| Variable | Description | Required |
|---|---|---|
| `OPENAI_API_KEY` | GPT-4o API key | ✅ |
| `DATABASE_URL` | PostgreSQL async URL | ✅ |
| `REDIS_URL` | Redis URL | ✅ |
| `SECRET_KEY` | JWT secret (64 chars) | ✅ |
| `SUBSCRIPTION_SECRET` | HMAC secret (32 chars) | ✅ |
| `CHROMA_HOST` | ChromaDB host | ✅ |
| `PLAN_MONTHLY_TOKENS` | Monthly token budget | default: 1000000 |
| `MAX_UPLOAD_MB` | Max file upload size | default: 50 |
| `RATE_LIMIT_REQUESTS` | Requests per minute | default: 60 |
| `GEO_DB_PATH` | MaxMind .mmdb path | optional |

---

## API Reference

### Public (requires subscription token in header `X-Subscription-Token`)
| Method | Endpoint | Description |
|---|---|---|
| POST | `/api/v1/chat/session` | Initialize a chat session |
| POST | `/api/v1/chat/chat` | Send a message |
| POST | `/api/v1/chat/track-click` | Track link clicks |

### Author (requires JWT Bearer token)
| Method | Endpoint | Description |
|---|---|---|
| GET/POST | `/api/v1/books/` | List / create books |
| PATCH/DELETE | `/api/v1/books/{id}` | Update / delete book |
| POST | `/api/v1/documents/upload` | Upload training document |
| GET | `/api/v1/documents/stream` | SSE ingestion status |
| GET | `/api/v1/analytics/overview` | KPI summary |
| GET | `/api/v1/settings/` | Get settings |
| PATCH | `/api/v1/settings/chatbot` | Update chatbot config |
| GET | `/api/v1/settings/embed-code` | Get embed snippet |

### SuperAdmin (requires JWT + superadmin role)
| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/v1/superadmin/clients` | List all authors |
| POST | `/api/v1/superadmin/clients/{id}/grant` | Grant subscription |
| POST | `/api/v1/superadmin/grants/{id}/revoke` | Revoke access |
| POST | `/api/v1/superadmin/grants/{id}/extend` | Extend subscription |
| POST | `/api/v1/superadmin/grants/{id}/bonus-tokens` | Add bonus tokens |
| GET | `/api/v1/superadmin/audit` | Audit log |

---

## Running Tests

```bash
cd backend

# All tests
pytest

# Unit tests only (fast, no DB)
pytest tests/unit/ -m unit

# Integration tests
pytest tests/integration/ -m integration

# With coverage report
pytest --cov=app --cov-report=html
```

---

## Technology Stack

**Backend**
- FastAPI 0.115 (async, production-grade)
- SQLAlchemy 2.0 (async ORM)
- Alembic (migrations)
- Celery + Redis (task queue, 6 scheduled tasks)
- ChromaDB (vector store)
- OpenAI GPT-4o (generation), text-embedding-3-small (embeddings)
- sentence-transformers (CrossEncoder re-ranking)
- transformers/BART (summarization)
- GeoIP2 (MaxMind, visitor analytics)
- structlog (structured logging)

**Frontend**
- Next.js 16 (App Router, TypeScript)
- Vanilla CSS (custom design system, glassmorphism)
- SSE (real-time ingestion status)
- SVG charts (zero dependencies)

**Infrastructure**
- Docker + Docker Compose (local)
- HuggingFace Spaces Docker (production)
- PostgreSQL 15 (primary DB)
- Redis 7 (sessions, cache, pub/sub)
- Vercel (admin dashboard CDN)

---

## Security

- **JWT tokens** — HS256, 30-min access + 7-day refresh
- **Subscription tokens** — HMAC-SHA256 signed, Redis revocation
- **5-layer validation** — signature → expiry → blacklist → DB status → token budget
- **TOTP 2FA** — SuperAdmin accounts require OTP
- **Rate limiting** — 60 req/min per IP (configurable)
- **Content guardrails** — 10 jailbreak patterns + NLI faithfulness
- **Password** — bcrypt (12 rounds)
- **Account lockout** — 5 failures → 30-min lock

---

## License

MIT © AuthorBot SaaS

---

*Built with ❤️ using FastAPI, Next.js, and GPT-4o*