Mindgate Policy Bot

RAG-based internal policy chatbot for Mindgate Solutions staff.
Ask natural-language questions about company rules, regulations, and policies — answers are grounded exclusively in the official policy PDF.

---

Architecture

User Question
    │
    ▼
┌──────────┐     ┌────────────────┐     ┌──────────────┐
│ Frontend │────▶│  FastAPI /chat  │────▶│   Retriever  │
│ (HTML)   │     │                │     │  (PostgreSQL +│
└──────────┘     │  Gemini 2.5    │◀────│  pgvector)   │
                 │  Flash         │     └──────────────┘
                 └────────────────┘
                        │
                        ▼
                  Grounded Answer

Stack: Python · FastAPI · Google Gemini 2.5 Flash · gemini-embedding-001 · PostgreSQL · pgvector · Docker · PyMuPDF

---

Project Structure

mindgate-policy-bot/
├── main.py              # FastAPI app — /chat, /ingest, /health endpoints
├── ingest.py            # PDF → chunks → embeddings → Postgres
├── retriever.py         # Postgres pgvector query + chunk retrieval
├── database.py          # SQLAlchemy models and Postgres connection
├── auth.py              # JWT authentication and password hashing
├── prompt.py            # System prompt template with grounding rules
├── watcher.py           # Auto-ingestion on PDF drop
├── docker-compose.yml   # PostgreSQL container configuration
├── start.ps1            # PowerShell launcher for Docker and API
├── requirements.txt     # Pinned Python dependencies
├── .env                 # Environment variables (GOOGLE_API_KEY)
├── README.md
├── frontend/
│   └── index.html       # Chat UI
└── data/
    └── policy.pdf       # ← Place your PDF here

---

Setup

1. Prerequisites

• Python 3.10+
• Docker Desktop (Required for PostgreSQL + pgvector)

2. Clone & install dependencies

# Create and activate a virtual environment (recommended)
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS / Linux

# Install dependencies
pip install -r requirements.txt

3. Set your Environment Variables

Create a .env file in the project root:

GOOGLE_API_KEY=your_google_api_key_here
# Optional: Change the JWT secret for production
JWT_SECRET_KEY=your_super_secret_key_here

Get a Google API key from Google AI Studio.

4. Add the policy PDF

Place your internal rules & regulations PDF at:

data/policy.pdf

5. Launch the Application

We have a convenient PowerShell script that ensures Docker is running, starts the PostgreSQL database container, waits for it to be ready, and then starts the FastAPI server.

# Run the launcher script
.\start.ps1

Open http://localhost:8000 in your browser to log in and use the chatbot.

User registration always creates a standard account. To provision an administrator, promote an existing account through a trusted database operation:

docker exec mindgate_postgres psql -U postgres -d mindgate_db -c "UPDATE users SET is_admin = TRUE WHERE email = 'admin@mindgate.com';"

---

API Reference

Method	Endpoint	Description
GET	/	Serves the chat UI
GET	/health	Health check
POST	/auth/register	Register a new user
POST	/auth/user/login	Authenticate a standard user
POST	/auth/admin/login	Authenticate an administrator
POST	/auth/login	Legacy login endpoint
POST	/ingest	Trigger PDF ingestion/re-ingestion
POST	/chat	Send a question, get an answer (JSON)
POST	/chat/stream	Stream answers token-by-token using Server-Sent Events (SSE)
GET	/chat/sessions	List all chat sessions for the current user
GET	/chat/history/{session_id}	Retrieve full message history for a specific session
DELETE	/chat/sessions/{session_id}	Delete a session and its message history

(All chat and ingestion endpoints are secured and require a valid JWT token)

---

Re-ingestion & Auto-ingestion

If the policy PDF is updated, the app needs to process it. You have three options:

1. Auto-ingestion (Watcher): The watcher is fully integrated into the FastAPI application. When the API starts, it automatically monitors the data/ directory. When a new/updated PDF is dropped, it places it in a sequential ingestion queue (avoiding concurrency or rate limits) and starts processing. You can also run it standalone using python watcher.py.
2. CLI Ingestion: Run python ingest.py manually.
3. API Ingestion: Make an authenticated POST request to http://localhost:8000/ingest.

---

Notes

• Vector Database: Uses PostgreSQL with the pgvector extension for efficient cosine-similarity search.
• Chat Memory: Conversations are organized into sessions and saved to Postgres, enabling persistent history. The UI provides a collapsible history sidebar with the option to switch between and delete chats.
• Streaming Response: Generates token-by-token streaming response to provide a fast, responsive user interface.
• Strict Grounding: The bot only answers from the indexed policy document — it will refuse unrelated questions. For legal/regulatory interpretation, the bot directs users to the compliance team.

---

License

Internal use only — Mindgate Solutions.