CherGPT-Basic: Custom Chat Assistant

CherGPT-Basic is a simplified, login-free ChatGPT-like interface designed for quick deployment in educational settings. Built with Streamlit and OpenAI, it provides educators with a customizable chat assistant that can be tailored to specific teaching and learning scenarios.

Mobile-friendly interface:

✨ Features

• Custom Instructions: Set and update custom instructions to guide student interactions with the AI
• Chat Log Management: Download and export chat logs as CSV for analysis
• Learning Analytics: Generate teaching and learning analytics based on collected chat logs
• Admin Panel: Secure admin access with password protection for managing settings
• App Description Customization: Customize the app description shown to users
• Persistent Storage: Chat history and instructions stored in PostgreSQL database
• Streaming Responses: Real-time streaming of AI responses for better user experience

🎯 Use Cases

CherGPT-Basic enables a variety of educational use cases:

• Historical Personas: Students can interact with historical figures for immersive learning
• Medical Simulations: Practice patient interactions with specific medical conditions
• Language Learning: Guided scenarios and escape rooms with comprehension checks
• Custom Tutoring: Create specialized tutoring assistants for specific subjects
• Interactive Assessments: Build conversational assessments with particular tasks as checks for understanding

📋 Prerequisites

• Python 3.8 or higher
• OpenAI API key
• PostgreSQL database (NeonDB recommended)
• Streamlit account (for deployment)
• GitHub account (for deployment)

🚀 Live Examples

• Physics CherGPT - Deployed from forked repository
• Physics CPDD CherGPT - Kah How's deployment

🛠️ Local Development Setup

1. Clone the Repository

git clone https://github.com/ghostleek/chergpt-basic-demo.git
cd chergpt-basic-demo

Note: This is a demo repository. For the original project, see String-sg/chergpt-basic.

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment Variables

Create a .streamlit/secrets.toml file with the following configuration:

OPENAI_API_KEY = "your-openai-api-key"
DATABASE_URL = "your-postgresql-connection-string"
ADMIN_PASSWORD = "your-admin-password"

4. Run Locally

streamlit run main.py

The application will be available at http://localhost:8501

🌐 Production Deployment

Overview

There are three main steps for deploying to production:

1. Set up your PostgreSQL database
2. Obtain your OpenAI API key
3. Deploy to Streamlit Cloud

Step 1: Database Setup (NeonDB)

We recommend using NeonDB for your PostgreSQL database. Get started here

1. Create an account: Visit the NeonDB console, log in, and create your account.

   

2. Create a new project: Create a free project with Singapore (or your preferred region) as the location. Choose any project and database name you like.

   

   

3. Copy connection string: Click the copy icon to get your database connection string. This allows you to store data persistently in CherGPT. Keep this secure - you'll need it in the next steps.

Step 2: OpenAI API Key

• If you're unsure how to create an OpenAI API key, see this guide.
• Keep this secure - you'll need it for deployment.

Note: Plans to migrate to open-source models are in progress.

Step 3: Deploy to Streamlit Cloud

1. Create accounts: First, create a Streamlit account and connect your GitHub account if you haven't already.

   

2. Deploy your app: Go to Streamlit Cloud, click "New app", select your forked repository (ghostleek/chergpt-basic-demo), set the main file path to main.py, and choose a custom domain for your app.

   

3. Set up secrets: Go to "Advanced settings" and add your configuration to secrets.toml:

   OPENAI_API_KEY = "your-openai-api-key"
   DATABASE_URL = "your-neondb-connection-string"
   ADMIN_PASSWORD = "your-chosen-admin-password"

   

4. Deploy: Click "Deploy" and wait a few minutes for the app to build and launch.

   

📁 Project Structure

chergpt-basic-demo/
├── app/
│   ├── chatlog/          # Chat log management and analytics
│   ├── db/               # Database connection and utilities
│   └── instructions/     # Custom instructions handling
├── main.py               # Main Streamlit application
├── sidebar.py            # Sidebar configuration and admin panel
├── requirements.txt      # Python dependencies
└── README.md            # This file

🔐 Security & Authentication

• Admin Access: Protected by password authentication (configure in secrets)
• Database Security: Connection strings stored as secrets, never committed to repository
• API Keys: OpenAI API keys stored securely in Streamlit secrets

For additional security with SSO authentication, check the Streamlit authentication guide.

🧪 Testing

Run the test suite:

pytest app_test.py

📊 Admin Features

Once authenticated as an admin, you can access:

• Edit Description: Customize the app description shown to users
• Custom Instructions: Set system prompts to guide the AI's responses
• Chatlog Management: Download chat logs and view analytics summaries
• Database Management: Drop tables if needed (use with caution)

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs and issues
• Suggest new features
• Submit pull requests
• Improve documentation

📝 License

This project is open-source. Feel free to explore and enhance the functionality of CherGPT-Basic according to your specific needs!

🆘 Troubleshooting

Common Issues

Database connection errors: Ensure your DATABASE_URL in secrets.toml is correct and the database is accessible.

OpenAI API errors: Verify your API key is valid and has sufficient credits.

Admin login not working: Check that ADMIN_PASSWORD is set correctly in your secrets configuration.

Local development issues: Ensure all dependencies are installed with pip install -r requirements.txt.

📚 Additional Resources

• Streamlit Documentation
• OpenAI API Reference
• NeonDB Documentation
• PostgreSQL Documentation

---

Need help? Open an issue in the GitHub repository.