README.md

metadata

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

---

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

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

2. Start all services

docker-compose up -d

3. Create SuperAdmin account

docker exec -it authorbot_api python -m app.scripts.create_superadmin \
  --email admin@yourcompany.com --password YourStrongPass123!

4. Start admin dashboard

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

# 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)

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 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

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