A production-ready Flask application for building RAG (Retrieval-Augmented Generation) systems with PDF document processing, semantic search, and OpenAI integration. Perfect for creating custom GPT actions or standalone knowledge bases.
- Fork this template - Click "Use Template" or fork this Repl
- Set up your secrets in Replit Secrets (see Setup Guide)
- Click Run - The application will start automatically
- Upload PDFs via the web interface or API
- Query your documents using natural language
- 📄 PDF Processing: Intelligent text extraction from PDF documents
- 🔍 Semantic Search: Natural language querying across all documents
- 🤖 OpenAI Integration: Ready for GPT Actions and custom AI workflows
- 🔐 Built-in Authentication: HTTP Basic Auth with session management
- 📊 Monitoring Dashboard: Health checks and database diagnostics
- 🛡️ Privacy Controls: PII filtering and secure logging
- 💾 Persistent Storage: Automatic backup and restore with Replit Object Storage
- ⚡ Production Ready: Configured for Replit deployment with Gunicorn
Status is that it works for me but this code is totally alpha so I doubt it will work for you, but I'm super interested in improving it.
The Custom GPT that this is enhancing needs a lot of love and config/prompt engineering that I'll be doing over the next weeks. I'll replace this with a link to a google doc on how to prompt engineer that GPT when I'm done.
- Features
- Quick Start
- API Usage
- Architecture
- Deployment
- Development
- Testing Tools
- Documentation
- License
- API Specification - Detailed API endpoint documentation
- Authentication Guide - Authentication setup and configuration
- Backup System Guide - ChromaDB backup and persistence details
- Replit Secrets Guide - Managing secrets in Replit environments
- Project Roadmap - Future development plans and research areas
- Privacy and PII Protection Guide - Comprehensive guide to privacy features and PII protection
- Privacy Demo Script - Interactive demonstration of privacy features
- PDF Processing: Extract text from PDF documents with memory-efficient processing
- Semantic Search: Search across all your documents using natural language queries
- Vector Database Storage: Store and retrieve document embeddings efficiently
- API Access: Programmatically upload documents and query the knowledge base
- Web Interface: User-friendly interface for uploading and querying documents
- Persistence: Robust backup and restore functionality with automatic rotation
- Monitoring: Built-in diagnostic tools for system health and database stats
- PII Filtering: Enhanced privacy controls for logs, headers, and sensitive data
- Backup and restore: Robust SQLite and ChromaDB persistence on Replit
Set these in Replit Secrets (Tools → Secrets):
| Secret Name | Description | Example |
|---|---|---|
OPENAI_API_KEY |
Your OpenAI API key | sk-... |
VKB_API_KEY |
Custom API key for your endpoints | vkb_your_secure_key_123 |
SESSION_SECRET |
Random string for sessions | your_random_32_char_string_here |
BASIC_AUTH_USERNAME |
Username for web access | admin |
BASIC_AUTH_PASSWORD |
Password for web access | your_secure_password |
- Go to OpenAI API Keys
- Create a new API key
- Add it to Replit Secrets as
OPENAI_API_KEY
- Click the Run button
- Wait for "Flask application configured successfully" in the console
- Access your app via the provided URL
- Go to
/monitoring/healthto check system status - Upload a test PDF via the web interface
- Try searching for content from your uploaded document
For detailed API documentation including authentication methods, endpoints, and example usage, see API Specification.
- Flask Backend: Web framework for interface and API
- PyMuPDF: PDF text extraction with optimized memory usage
- OpenAI: Text embeddings and query processing
- ChromaDB: Vector database for semantic search
- Object Storage: Persistent storage for ChromaDB data with automatic backup rotation
- Backup System: For details, see Backup System Guide
-
Fork the Repository
- Create a new Replit project importing from GitHub repository
-
Set Required Environment Variables in Replit Secrets
OPENAI_API_KEY: Your OpenAI API key for embeddings and queriesVKB_API_KEY: Custom API key for API endpoint authenticationSESSION_SECRET: Random string for secure session managementBASIC_AUTH_USERNAME: Secure username for HTTP Basic AuthenticationBASIC_AUTH_PASSWORD: Strong password for HTTP Basic Authentication
IMPORTANT: For production deployments, always use Replit Secrets rather than environment variables in .env files or code. See Authentication Guide for detailed setup instructions.
-
Install Dependencies
- Replit will automatically install dependencies from pyproject.toml
-
Configure Storage
- Ensure persistent storage is enabled
- For production, enable Replit's Object Storage
- The backup system automatically manages data persistence (see Backup System Guide)
- In disk-constrained environments, use the
--skip-backupflag with restore operations
-
Disk Space Management
- The system is designed to handle disk quota limitations
- For cleanup:
python utils/delete_backup_history.py --force - For restore without local backup:
python utils/object_storage.py restore --skip-backup - All restorations during application startup automatically adapt to disk constraints
-
Run the Application
- Use the "Run" button in Replit
- Application will start on the default Replit port
- First run will initialize the ChromaDB database
-
Verify Functionality
- Navigate to the web interface
- Upload a test PDF
- Test search functionality
- Check the /monitoring/database-diagnostic endpoint
This is just some auto-generated stuff that Claude wrote - I haven't deployed this on bare metal.
-
Clone the Repository
git clone https://github.com/richbodo/VectorKnowledgeBase.git cd VectorKnowledgeBase -
Set Up Environment
python -m venv venv source venv/bin/activate pip install -r requirements.txt -
Configure Environment Variables
# Required API keys export OPENAI_API_KEY="your_openai_api_key" export VKB_API_KEY="your_custom_api_key" # Authentication and security export SESSION_SECRET="your_random_secret_key" export BASIC_AUTH_USERNAME="your_secure_username" export BASIC_AUTH_PASSWORD="your_secure_password" # Optional: Configure ChromaDB location export CHROMADB_DIR="/path/to/persistent/storage"
Security Note: In production, use a secrets management solution instead of setting environment variables directly in shell scripts.
-
Run for Development
python main.py
-
Run for Production
gunicorn --bind 0.0.0.0:8080 --workers 4 --timeout 120 'main:create_app()' -
Configure Nginx (Optional)
- Set up Nginx as a reverse proxy
- Configure SSL with Let's Encrypt
- Set appropriate cache headers
-
Set Up Systemd Service (Optional)
- Create a systemd service file for automatic startup
- Enable log rotation
- Configure automatic restarts
For more information on development and future research areas, please refer to Project Roadmap.
The following scripts are available for testing privacy and PII protection features:
utils/test_privacy.py- Test script for privacy controls in API requestsutils/test_privacy_filter.py- Test script for privacy log filter functionalityutils/run_privacy_tests.sh- Shell script to run comprehensive privacy testsdocs/privacy_demo.py- Demonstration of privacy features
- Developers should start with the implementation guides
- End users should refer to the user guides
- System administrators should review both for complete understanding
When working with the Vector Knowledge Base application:
- Always prioritize privacy and security
- Regularly test privacy controls after making changes
- Keep documentation updated with implementation changes
- Report any privacy or security concerns immediately
When adding to this documentation set:
- Maintain consistent formatting
- Include concrete examples
- Separate technical and user-focused content
- Cross-reference related documentation
This project is GPLv3 licensed. See LICENSE file for details.
Documentation last updated: March 17, 2025