README.md

metadata

title: Chatty - Ethics Chat
emoji: 💬
colorFrom: yellow
colorTo: purple
sdk: gradio
sdk_version: 5.0.1
app_file: app.py
pinned: false
license: mit

A secure web-based chat interface with user authentication that connects to the findEthics-Atlas API for ethical discussions and guidance.

Features

• User Authentication: Secure registration and login system
• Personalized Chat History: Each user's conversations are saved and restored
• Minimal and clean UI: Simple, responsive chat interface
• Real-time chat: Instant messaging with the ethics AI
• Security Features: CSRF protection, rate limiting, secure sessions
• Error handling: Robust error handling for API failures
• Mobile-friendly: Responsive design that works on all devices
• Loading states: Visual feedback during API calls

Technology Stack

• Backend: Flask web framework with Flask-Login
• Database: MongoDB for user accounts and chat history
• Authentication: Secure password hashing with Werkzeug
• Security: CSRF protection, rate limiting, secure sessions
• Frontend: HTML, CSS, JavaScript (ES6)
• API Integration: HTTP requests to findEthics-Atlas endpoint
• Deployment: Hugging Face Spaces, Docker, or traditional servers

Usage

First Time Setup

1. Open the application in your web browser
2. Register an account with your email and password
3. Log in with your credentials

Using the Chat

1. Access the chat interface (automatically redirected after login)
2. Type your message in the chat input field
3. Press Enter or click the Send button
4. Wait for the response from the ethics AI
5. Continue the conversation - your history is automatically saved

Account Management

• Logout: Click the logout button to securely end your session
• Session Management: Sessions automatically expire after 24 hours for security
• Chat History: Your conversations are preserved across sessions

The application connects to the findEthics-Atlas API to provide ethical guidance and responses to your questions, while maintaining your personal conversation history.

API Integration

This application uses the https://findEthics-Atlas.hf.space/chat API for generating responses.

Request Format

{
  "prompt": "Your question here",
  "history": []
}

Response Format

{
  "response": "AI response text",
  "search_results": []
}

Setup and Installation

Prerequisites

• Python 3.8 or higher
• MongoDB database (MongoDB Atlas recommended)
• Git

Local Development Setup

1. Clone the repository

   git clone <repository-url>
   cd chatty
   

2. Create virtual environment

   python -m venv atlas_env
   source atlas_env/bin/activate  # On Windows: atlas_env\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Set up environment configuration

   python deploy.py setup-dev
   

   This creates a .env file from the template.

5. Configure environment variables Edit .env file and set:

   SECRET_KEY=your-secret-key-here
   MONGODB_URL=mongodb+srv://username:password@cluster.mongodb.net/database
   MONGODB_DATABASE=Atlas
   

6. Run the application

   ./start.sh
   

   Or directly: python app.py

7. Open in browser Navigate to http://localhost:7860

MongoDB Setup

Option 1: MongoDB Atlas (Recommended)

1. Create account at MongoDB Atlas
2. Create a new cluster
3. Create database user with read/write permissions
4. Get connection string from Atlas dashboard
5. Add connection string to .env as MONGODB_URL

Option 2: Local MongoDB

1. Install MongoDB locally
2. Start MongoDB service
3. Set MONGODB_URL=mongodb://localhost:27017/chatty in .env

Project Structure

Chatty/
├── app.py                 # Main Flask application
├── config.py              # Configuration management
├── auth.py                # Authentication utilities
├── models.py              # Database models (User, ChatSession)
├── database.py            # MongoDB connection utilities
├── deploy.py              # Deployment and configuration tools
├── requirements.txt       # Python dependencies
├── .env.example           # Environment variables template
├── start.sh               # Application startup script
├── templates/
│   ├── base.html         # Base template with navigation
│   ├── login.html        # Login form
│   ├── register.html     # Registration form
│   ├── index.html        # Chat interface
│   └── errors/           # Error page templates
├── static/
│   ├── css/
│   │   ├── style.css     # Main stylesheet
│   │   └── auth.css      # Authentication form styles
│   └── js/
│       └── chat.js       # Frontend JavaScript
├── Test/                  # Test suite
└── docs/
    └── PRODUCTION_DEPLOYMENT.md  # Production deployment guide

Key Components

Backend Components

• Flask Routes: Authentication (/login, /register, /logout) and chat (/, /chat, /api/chat)
• User Management: Registration, login, session management
• Database Models: User accounts and chat session storage
• Security: CSRF protection, rate limiting, secure password hashing
• Configuration: Environment-based configuration management

Frontend Components

• Authentication UI: Login and registration forms
• Chat Interface: Real-time messaging with history
• Responsive Design: Mobile-first CSS architecture
• Error Handling: User-friendly error messages and validation

Security Features

• Password Security: Werkzeug password hashing (PBKDF2)
• Session Management: Flask-Login with secure cookies
• CSRF Protection: Form-based CSRF tokens
• Rate Limiting: Login attempt limiting
• Input Validation: Server and client-side validation

Configuration

Environment Variables

The application uses environment variables for configuration. Copy .env.example to .env and configure:

Required Variables

• SECRET_KEY: Flask secret key (generate with python deploy.py gen-secret)
• MONGODB_URL: MongoDB connection string
• MONGODB_DATABASE: Database name (default: Atlas)

Optional Variables

• FLASK_ENV: Environment mode (development, production, testing)
• SESSION_LIFETIME_HOURS: Session duration (default: 24)
• MAX_LOGIN_ATTEMPTS: Failed login limit (default: 5)
• API_TIMEOUT: External API timeout (default: 30)
• LOG_LEVEL: Logging level (default: INFO)

Configuration Management

Use the deployment script for configuration tasks:

# Generate secure secret key
python deploy.py gen-secret

# Set up development environment
python deploy.py setup-dev

# Check production readiness
python deploy.py check-prod

# Generate production environment template
python deploy.py gen-prod-env

Testing

Running Tests

# Install test dependencies
pip install -r Test/test_requirements.txt

# Run all tests
python Test/run_tests.py

# Run specific test categories
python -m pytest Test/test_auth_unit.py      # Unit tests
python -m pytest Test/test_auth_integration.py  # Integration tests

Test Categories

• Unit Tests: Individual component testing
• Integration Tests: Full authentication flow testing
• API Tests: External API integration testing

Deployment

Development Deployment

export FLASK_ENV=development
./start.sh

Production Deployment

For production deployment, see PRODUCTION_DEPLOYMENT.md for comprehensive instructions including:

• Security configuration
• Database setup
• HTTPS configuration
• Environment validation
• Monitoring and logging

Quick Production Setup

# Generate production configuration
python deploy.py gen-prod-env

# Edit .env.production with your values
# Then deploy:
export FLASK_ENV=production
./start.sh

Deployment Platforms

• Hugging Face Spaces: Direct deployment with environment variables
• Docker: Use provided Dockerfile
• Traditional Servers: systemd service configuration
• Cloud Platforms: AWS, GCP, Azure compatible

Troubleshooting

Common Issues

1. Database Connection Errors

   # Test database connection
   python -c "from database import test_connection; test_connection()"
   

2. Configuration Issues

   # Validate configuration
   python config.py
   

3. Authentication Problems

   • Check SECRET_KEY is set and secure
   • Verify MongoDB connection
   • Ensure HTTPS in production

4. Session Issues

   • Check cookie settings for your domain
   • Verify session configuration
   • Clear browser cookies

Getting Help

• Check application logs for detailed error messages
• Review configuration with python deploy.py check-prod
• Test individual components with provided test scripts
• Consult PRODUCTION_DEPLOYMENT.md for deployment issues

Security

Security Features

• Password Hashing: Secure PBKDF2 password storage
• Session Security: HTTPOnly, Secure, SameSite cookies
• CSRF Protection: Form-based CSRF tokens
• Rate Limiting: Brute force protection
• Input Validation: Server and client-side validation
• SQL Injection Prevention: MongoDB parameterized queries

Security Best Practices

• Use HTTPS in production
• Set strong SECRET_KEY
• Configure MongoDB authentication
• Regular security updates
• Monitor authentication logs
• Implement proper firewall rules

API Integration

This application integrates with the findEthics-Atlas API for AI responses.

Request Format

{
  "prompt": "Your question here",
  "history": [
    {"message": "Previous message", "response": "Previous response"}
  ]
}

Response Format

{
  "response": "AI response text",
  "search_results": []
}

Authentication Integration

• User ID is tracked with each API request
• Chat history is maintained per user
• Session context is preserved across requests

License

MIT License - see LICENSE file for details.