Skip to content

String-sg/chergpt-basic

BranchesTags

Repository files navigation

Chergpt-Basic: Custom Chat Assistant

Chergpt-Basic is a simplified, login-free ChatGPT-like interface designed for quick deployment and educational use.

  • ✅ Mobile-friendly
  • ✅ Easy to deploy on Streamlit
  • ✅ Beginner-friendly
  • 🆕 RAG support (Retrieval-Augmented Generation via vector embeddings)
  • 🔒 Optional password protection (global and admin)
  • 📊 Built-in chat analytics and logging
  • 📚 PDF document processing for context-aware responses

Desktop Preview

image

Mobile Preview

image

📋 Table of Contents

🌟 Features

Core Capabilities

  • Custom Instructions: Add tailored instructions to guide student or user interactions
  • Chat Logging: Automatically store all conversations in a PostgreSQL database (NeonDB)
  • Analytics Dashboard: Generate learning/teaching analytics from chatlogs
  • Download Chatlogs: Export chat history as CSV for analysis
  • User Name Tracking: Track conversations by user name

Advanced Features

  • 🧠 RAG Support (Retrieval-Augmented Generation):

    • Upload PDF documents through the admin web interface
    • Automatic text extraction, chunking, and embedding generation
    • Context-aware responses using pgvector similarity search
    • Support for multiple PDF files with duplicate detection
    • Secure in-memory processing (files never stored on disk)
    • Smart query detection for context retrieval

  • 🔒 Password Protection:

    • Admin Password: Protects admin panel for managing instructions, uploading PDFs, and viewing analytics
    • Global Password: Optional single password to restrict access to the entire application
    • See Streamlit authentication guide for additional options

  • 📱 Mobile Responsive: Optimized interface for both desktop and mobile devices

  • ☁️ Cloud Ready: Easy deployment on Streamlit Cloud with simple configuration

📦 Prerequisites

Before you begin, ensure you have the following:

  1. Python 3.8 or higher installed on your system
  2. OpenAI API Key - Get one here
  3. NeonDB Account (free tier available) - Sign up here
  4. Git (for cloning the repository)
  5. Streamlit Account (for cloud deployment) - Create account

System Requirements

  • Operating System: Windows, macOS, or Linux
  • RAM: Minimum 2GB (4GB recommended for PDF processing)
  • Disk Space: At least 500MB free space
  • Internet connection for API calls

⚡ Quickstart (copy–paste setup)

Want to deploy immediately? You only need 4 configuration values in your secrets.toml:

OPENAI_API_KEY = "your_api_key_here"
DB_CONNECTION_STRING = "your_neondb_string_here"
ADMIN_PASSWORD = "your_secure_admin_password_here"
GLOBAL_PASSWORD = "optional_password_here"

Quick Reference:

  • OPENAI_API_KEY: Get from OpenAI API Keys
  • DB_CONNECTION_STRING: Get from NeonDB Console after creating a project
  • ADMIN_PASSWORD: Required - Create your own secure password for admin access
  • GLOBAL_PASSWORD: Optional - Set this to require a password for all users to access the app

👉 Once these are configured, proceed to Deploy on Streamlit and you're live!

🛠️ Installation

Local Development Setup

Follow these steps to run Chergpt-Basic on your local machine:

Step 1: Clone the Repository

git clone https://github.com/String-sg/chergpt-basic.git
cd chergpt-basic

Step 2: Create a Virtual Environment (Recommended)

For Windows:

python -m venv venv
venv\Scripts\activate

For macOS/Linux:

python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

The required packages include:

  • streamlit - Web application framework
  • openai - OpenAI API client
  • psycopg2-binary - PostgreSQL database adapter
  • PyPDF2 - PDF text extraction
  • tiktoken - Token counting for embeddings
  • pgvector - Vector similarity search support
  • pytest - Testing framework
  • streamlit-feedback - User feedback components

Step 4: Set Up Configuration

Create a .streamlit/secrets.toml file in your project directory:

mkdir -p .streamlit
touch .streamlit/secrets.toml

Add your configuration (see Configuration section below):

OPENAI_API_KEY = "sk-..."
DB_CONNECTION_STRING = "postgresql://user:password@host/database"
ADMIN_PASSWORD = "your_secure_admin_password"
GLOBAL_PASSWORD = "optional_global_password"  # Optional

Step 5: Run the Application

streamlit run main.py

The app will open in your browser at http://localhost:8501

🔧 Configuration

Database Setup (NeonDB)

  1. Create a NeonDB Account: Go to https://console.neon.tech/
  2. Create a New Project:
    • Click "Create Project"
    • Choose a project name
    • Select a region (choose Singapore or closest to your users)
  3. Get Connection String:
    • Navigate to your project dashboard
    • Click on "Connection Details"
    • Copy the connection string (it looks like: postgresql://user:password@host/database)
    • Use this as your DB_CONNECTION_STRING

Note: The free tier of NeonDB provides:

  • 3GB storage
  • Always available (no hibernation)
  • Perfect for small to medium deployments

OpenAI API Setup

  1. Create an OpenAI Account: Visit https://platform.openai.com/
  2. Generate API Key:
    • Go to API Keys page
    • Click "Create new secret key"
    • Important: Copy and save the key immediately (you won't be able to see it again)
  3. Add Credits: Ensure your OpenAI account has available credits for API usage

Pricing Information:

  • The app uses gpt-4o-mini by default (cost-effective)
  • Embeddings use text-embedding-ada-002
  • Monitor usage in your OpenAI dashboard

💡 Beginner Tip: Follow this step-by-step guide for detailed instructions on getting your OpenAI API key.

Password Configuration

Admin Password (Required):

  • Set ADMIN_PASSWORD in your secrets.toml
  • Grants access to:
    • Custom instruction editing
    • PDF upload and RAG management
    • Chat log analytics and downloads
    • App title and description customization

Global Password (Optional):

  • Set GLOBAL_PASSWORD if you want to restrict general access
  • When configured, all users must enter this password to use the chat
  • Leave empty or omit to allow unrestricted access to the chat interface

RAG (PDF Upload) Configuration

No additional configuration needed! Once your database is set up:

  1. Log in as admin (using ADMIN_PASSWORD)
  2. Navigate to "📤 Upload New Materials" in the sidebar
  3. Upload PDF files (up to 50MB, max 1000 pages)
  4. Files are processed automatically and made searchable

Security Features:

  • Files are processed entirely in memory
  • Original PDFs are never stored on disk
  • Only text chunks and embeddings are stored in the database
  • Automatic duplicate detection prevents re-processing

🚀 Getting Started with Deployment

There are 3 simple steps to deploy your own Chergpt-Basic app:

  1. Set up your database (for storing chatlogs).
  2. Get your OpenAI API key.
  3. Deploy to Streamlit.

1. Set up your backend (Database)

We recommend NeonDB (free tier works well).

  1. Create an account at Neon.
  2. Start a free project (choose Singapore region if relevant).
  3. Copy your DB connection string — you'll need this later.

📌 This string is what allows Chergpt-Basic to save chat data. Keep it safe.

2. Get your OpenAI API key

  1. Go to OpenAI API keys.
  2. Click Create new secret key.
  3. Copy it somewhere safe — you'll need it for deployment.

💡 Not sure how? Follow this beginner-friendly guide.

3. Deploy on Streamlit

Click below to auto-deploy:
👉 Deploy Chergpt-Basic

Then:

  1. Create a Streamlit account (free).

  2. Connect your GitHub account.

  3. Fork the repo → String-sg/chergpt-basic.

  4. In Advanced Settings → Secrets.toml, paste:

    OPENAI_API_KEY = "your_api_key_here"
DB_CONNECTION_STRING = "your_neondb_string_here"
ADMIN_PASSWORD = "set this to what you want"
GLOBAL_PASSWORD = "optional_password_here"

Alternative: Deploy without GitHub Account

Don't have a GitHub account and just want to deploy without cloning? Sure, you can!

  1. Go to streamlit.io and create an account, then login

  2. In the top right corner, click Create app

    image

  3. Select Deploy a public app from Github

    image

  4. Setup your app with the following fields:

    • Repository = https://github.com/String-sg/chergpt-basic/ (You can click "Paste Github URL" and enter this)
    • Branch = main
    • Main file path = main.py
    • APP URL = choose your own or use the default
    image

  5. Click on Advanced settings, paste in the configuration details you previously obtained

    image

🎯 Use Cases

Chergpt-Basic is ideal for educational and interactive scenarios:

1. Educational Role-Play & Personas

Create immersive learning experiences by configuring the chatbot to assume different roles:

  • Historical Figures: Students can interview historical personalities (e.g., Albert Einstein, Marie Curie)
  • Medical Scenarios: Practice patient interactions for healthcare training
  • Character Role-Play: Language learning through conversational practice with fictional characters

Example Setup:

Custom Instructions: "You are Isaac Newton. Respond to students' questions about 
physics and mathematics from the perspective of a 17th-century scientist. Use 
historical context but explain concepts clearly."

2. Guided Language Learning

Build interactive "escape rooms" or challenge-based learning:

  • Chinese Language Tasks: Students complete tasks like ordering food, asking for directions
  • Spanish Conversation Practice: Progressive difficulty levels with checkpoint validation
  • Vocabulary Building: Contextual word usage in realistic scenarios

Example Setup:

Custom Instructions: "You are a shopkeeper in Shanghai. Only respond in Mandarin Chinese. 
Help students practice ordering items. After they successfully order 3 items, 
congratulate them and move to the next checkpoint."

3. Interactive Lessons with Analytics

Run structured lessons and monitor student progress:

  • Track student questions and responses
  • Identify common misconceptions through chat log analysis
  • Generate summaries of learning patterns
  • Download data for further analysis

Example Use:

  • Physics problem-solving sessions
  • Economics concept explanations with RAG-powered textbook references
  • Step-by-step programming tutorials

4. Subject-Specific Tutoring with RAG

Upload course materials (PDFs) to create a subject-specific tutor:

  • Economics Tutor: Upload textbooks, lecture notes, and the bot answers from course materials
  • Science Lab Assistant: Upload lab manuals for procedure guidance
  • Legal Studies: Upload case law documents for reference-based learning

How it Works:

  1. Admin uploads relevant PDF documents
  2. System automatically processes and creates searchable embeddings
  3. Student asks a question
  4. Bot searches uploaded materials for relevant context
  5. Responds with context-aware answers based on course materials

5. Assessment & Quiz Modes

Configure the bot to conduct assessments:

  • Multiple-choice quizzes with instant feedback
  • Open-ended questions with guided responses
  • Practice exams with performance tracking

🚀 Live Examples

See Chergpt-Basic in action:

These examples showcase different configurations and use cases for educational purposes.

🐛 Troubleshooting

Common Issues and Solutions

1. Database Connection Errors

Issue: psycopg2.OperationalError: could not connect to server

Solutions:

  • Verify your DB_CONNECTION_STRING is correct in secrets.toml
  • Check that your NeonDB project is active (not suspended)
  • Ensure you're using the correct connection string format: postgresql://user:password@host/database
  • Test the connection string using a PostgreSQL client or command line: 
    psql "your_connection_string_here"

Tip: The connection string should look like: postgresql://username:password@ep-xxxxx.region.aws.neon.tech/neondb

2. OpenAI API Errors

Issue: openai.error.AuthenticationError: Incorrect API key provided

Solutions:

  • Verify your API key in secrets.toml starts with sk-
  • Ensure there are no extra spaces or quotes in the key
  • Check that your OpenAI account has available credits
  • Generate a new API key from OpenAI dashboard

Issue: Rate limit exceeded

Solutions:

  • Wait a few minutes before retrying
  • Upgrade your OpenAI plan for higher rate limits
  • Reduce the frequency of requests in your application

3. PDF Upload Issues

Issue: File too large or Processing failed

Solutions:

  • Ensure PDF is under 50MB
  • Check PDF page count is under 1,000 pages
  • Verify PDF is not encrypted or password-protected
  • Try converting the PDF to a simpler format (remove images if possible)

Issue: No text extracted from PDF

Solutions:

  • PDF might be image-based (scanned) - use OCR tools first
  • Try opening the PDF and copying text manually to verify it contains extractable text
  • Use a different PDF or re-save the document

4. Streamlit Deployment Issues

Issue: ModuleNotFoundError: No module named 'xyz'

Solutions:

  • Verify requirements.txt contains all dependencies
  • Check that Streamlit Cloud is using the correct Python version (3.8+)
  • Rebuild the app from Streamlit Cloud dashboard

Issue: Secrets not found

Solutions:

  • Go to Streamlit Cloud dashboard → Your App → Settings → Secrets
  • Ensure all required secrets are defined: 
    OPENAI_API_KEY = "sk-..."
DB_CONNECTION_STRING = "postgresql://..."
ADMIN_PASSWORD = "your_password"
  • Click "Save" after adding secrets
  • Reboot the app

5. Admin Login Not Working

Issue: "Incorrect password" even with correct password

Solutions:

  • Check for extra spaces in ADMIN_PASSWORD in secrets.toml
  • Ensure you're entering the password exactly as defined
  • Clear browser cache and cookies
  • Try in an incognito/private browser window

6. RAG Not Retrieving Context

Issue: Uploaded PDFs but no context is retrieved

Solutions:

  • Verify PDFs were successfully processed (check admin panel → RAG Management)
  • Ensure RAG is enabled in admin settings (toggle should be ON)
  • Check that your query is related to the uploaded content
  • Review the similarity threshold - lower it if needed in the code

Issue: pgvector extension not found

Solutions:

  • Ensure NeonDB has pgvector extension enabled (should be automatic)
  • Try running the initialization manually from admin panel
  • Contact NeonDB support if the extension is not available

7. Local Development Issues

Issue: streamlit: command not found

Solutions:

  • Ensure virtual environment is activated
  • Reinstall streamlit: pip install streamlit
  • Check Python PATH: which python or where python

Issue: Port 8501 already in use

Solutions:

  • Kill existing Streamlit process:
    • Windows: taskkill /F /IM streamlit.exe
    • Mac/Linux: pkill -f streamlit
  • Run on different port: streamlit run main.py --server.port 8502

8. Performance Issues

Issue: Slow response times

Solutions:

  • Check OpenAI API status: status.openai.com
  • Verify database performance (NeonDB free tier may have limits)
  • Reduce RAG chunk retrieval count (modify top_k parameter)
  • Consider upgrading to a paid plan for better performance

Getting Additional Help

If you encounter issues not covered here:

  1. Check existing GitHub issues: GitHub Issues
  2. Create a new issue: Include:
    • Error messages (sanitize sensitive information)
    • Steps to reproduce
    • Your environment (Python version, OS)
    • Deployment method (local vs Streamlit Cloud)
  3. Streamlit Community Forum: discuss.streamlit.io
  4. Review logs: Check Streamlit Cloud logs or terminal output for detailed error messages

📚 Documentation & Resources

Official Documentation

Related Technologies

Tutorials & Guides

  • Getting OpenAI API Key: Teacher Tech Guide - Beginner-friendly walkthrough
  • RAG (Retrieval-Augmented Generation): Understanding how context-aware AI works
  • Prompt Engineering: OpenAI Guide - Writing effective custom instructions

Community & Support

Example Projects & Inspiration

🤝 Contributing

We welcome contributions to Chergpt-Basic! Here's how you can help:

Ways to Contribute

  1. Report Bugs: Open an issue on GitHub with details about the bug
  2. Suggest Features: Share your ideas for new features or improvements
  3. Submit Pull Requests: Fix bugs or add features
  4. Improve Documentation: Help make the README and docs better
  5. Share Use Cases: Tell us how you're using Chergpt-Basic

Development Setup

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/YOUR_USERNAME/chergpt-basic.git
  3. Create a feature branch: git checkout -b feature/your-feature-name
  4. Make your changes and test thoroughly
  5. Commit your changes: git commit -am 'Add some feature'
  6. Push to the branch: git push origin feature/your-feature-name
  7. Open a Pull Request

Testing

Run the test suite before submitting PRs:

pytest

Run specific tests:

pytest test_rag.py
pytest test_user_storage.py
pytest app_test.py

Code Style

This project uses Pylint for code quality. Run it locally:

pylint $(git ls-files '*.py')

📄 License

This project is open source. Please check the repository for license details.

🙏 Acknowledgments

📧 Contact

For questions, issues, or collaboration opportunities:

  • Open an issue on GitHub
  • Check existing documentation and troubleshooting guide above

Made with ❤️ for educators and learners

About

No backend, no login, vanilla ChatGPT-like interface with scaffolded code for immediate deployment

Topics

ai chatbot

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

26 forks
Report repository

Releases 1

v1.0.0 Latest
Feb 4, 2024

Packages

No packages published

Contributors 5

Languages