HyperLogic AI ChatBot

A powerful, fast, and feature-rich AI chatbot application with Python FastAPI backend and React frontend, featuring multi-provider LLM support, real-time messaging, conversation memory, and a beautiful responsive interface.

✨ Features

🚀 Core Features

• Multi-Provider LLM Support: Google Gemini and more
• Real-time Chat: WebSocket-based instant messaging
• Conversation Memory: Context-aware conversations with persistent memory
• Fast Performance: Optimized for speed and responsiveness
• Beautiful UI: Modern, responsive design with Tailwind CSS

🎨 User Interface

• Responsive Design: Works perfectly on desktop, tablet, and mobile
• Dark/Light Theme: Customizable appearance
• Smooth Animations: Framer Motion powered interactions
• Real-time Typing Indicators: See when AI is responding
• Message Actions: Copy, like, regenerate, and more

🧠 AI Capabilities

• Context Awareness: Remembers conversation history
• Provider Switching: Switch between different AI models
• Fallback Support: Automatic fallback if primary provider fails
• Response Streaming: Real-time response generation
• Memory Management: Intelligent conversation summarization

📊 Conversation Management

• Conversation History: Browse and search past conversations
• Export/Import: Backup and restore conversations
• Bulk Operations: Delete multiple conversations
• Search & Filter: Find conversations quickly
• Auto-save: Automatic conversation persistence

🛠️ Technology Stack

Frontend

• React 18: Modern React with hooks and context
• TypeScript: Type-safe JavaScript development
• Node.js: JavaScript runtime for development
• Vite: Fast build tool and dev server
• Tailwind CSS: Utility-first CSS framework
• Framer Motion: Smooth animations and transitions
• Socket.io Client: Real-time communication
• Axios: HTTP client for API calls
• React Router: Client-side routing
• React Hot Toast: Beautiful notifications

Backend (Python)

• FastAPI: Modern web framework for building APIs
• Uvicorn: ASGI server for FastAPI
• WebSockets: Real-time communication
• Google API: Gemini models integration
• Pydantic: Data validation and serialization
• Python-dotenv: Environment variable management
• SlowAPI: Rate limiting
• Socket.IO: Additional WebSocket support

Database

• MongoDB: NoSQL database with localhost-only access
• SQLite: Fallback database for development
• Dual Support: Automatic database detection and switching
• Local Storage: All data stored locally, no external connections

Docker & Deployment

• Docker Compose: Multi-container orchestration
• MongoDB Container: Local database with initialization
• Nginx: Reverse proxy for production

🚀 Quick Start

Prerequisites

• Python v3.14+ and pip (for backend)
• Node.js v25+ and npm (for frontend development)
• TypeScript knowledge (recommended)
• Docker Desktop (for containerized deployment)
• API keys for your preferred LLM providers

Installation

1. Clone the repository

   git clone https://github.com/sudo-de/HyperLogic_AI_ChatBot.git
   cd HyperLogic_AI_ChatBot

2. Install dependencies

   npm run install-all

   This will:

   • Install frontend dependencies (React)
   • Create Python virtual environment
   • Install Python backend dependencies

3. Environment Setup

   cp env.example .env

   Edit .env and add your API keys:

   GOOGLE_API_KEY=your_google_api_key_here
   PORT=5000
   CORS_ORIGIN=http://localhost:3000

4. Start with Docker (Recommended)

   # Start MongoDB and backend
   docker compose up -d mongodb hyperlogic-ai
   
   # Start frontend locally
   cd web && npm run dev

5. Start without Docker (Development)

   ./start.sh

   This will start both the Python backend server (port 5000) and React frontend (port 3000).

Development Commands

# Docker Commands
docker compose up -d                    # Start all services
docker compose up -d mongodb            # Start only MongoDB
docker compose up -d hyperlogic-ai      # Start only backend
docker compose down                     # Stop all services
docker compose logs                     # View logs

# Frontend Development
cd web
npm install                            # Install dependencies
npm run dev                            # Start development server
npm run build                          # Build for production
npm run preview                        # Preview production build

# Backend Development
cd server
python -m venv venv                    # Create virtual environment
source venv/bin/activate               # Activate virtual environment
pip install -r requirements.txt       # Install dependencies
python run.py                          # Start backend server

# Full Stack Development
./start.sh                             # Start both frontend and backend

🔧 Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	5000
NODE_ENV	Environment	development
GOOGLE_API_KEY	Google API key	-
CORS_ORIGIN	Frontend URL	http://localhost:3000
MONGODB_URL	MongoDB connection	mongodb://127.0.0.1:27017/hyperlogic_ai
DATABASE_URL	SQLite fallback	sqlite:///./hyperlogic_ai.db

Database Configuration

MongoDB (Production):

MONGODB_URL=mongodb://hyperlogic:password@127.0.0.1:27017/hyperlogic_ai?authSource=admin

SQLite (Development):

DATABASE_URL=sqlite:///./hyperlogic_ai.db

Automatic Detection:

• If MONGODB_URL is set → Uses MongoDB
• If not set → Falls back to SQLite

Adding New LLM Providers

1. Install the provider SDK

   npm install provider-sdk

2. Add to LLMProvider service

   // In server/services/llmProvider.js
   addProvider('new-provider', newProviderInstance);

3. Update frontend provider list

   // In web/src/components/Settings.js
   const providers = ['google', 'new-provider'];

📱 Usage

Starting a Conversation

1. Click "New Conversation" in the sidebar
2. Type your message in the input field
3. Press Enter or click Send
4. Watch the AI respond in real-time

Managing Conversations

• Search: Use the search bar to find specific conversations
• Filter: Sort by date, title, or message count
• Export: Download conversations as JSON files
• Delete: Remove individual or multiple conversations

Settings

• AI Provider: Switch between different AI models
• Theme: Choose light, dark, or auto theme
• Font Size: Adjust text size for better readability
• Notifications: Enable/disable notifications

🏗️ Architecture

Backend Architecture (Python)

server/
├── main.py                  # FastAPI application
├── run.py                   # Application runner
├── requirements.txt         # Python dependencies
├── models/
│   └── schemas.py          # Pydantic models
└── services/
    ├── llm_provider.py     # Multi-provider LLM integration
    ├── conversation_manager.py # Conversation management
    ├── memory_manager.py   # Memory and context management
    └── websocket_manager.py # WebSocket handling

Frontend Architecture

web/src/
├── components/              # React components
│   ├── ChatInterface.js     # Main chat interface
│   ├── MessageBubble.js     # Individual message component
│   ├── Sidebar.js          # Conversation sidebar
│   ├── Settings.js         # Settings panel
│   └── Header.js           # App header
├── context/
│   └── AppContext.js       # Global state management
├── services/
│   ├── socketService.js    # WebSocket communication
│   └── apiService.js       # HTTP API calls
└── App.js                  # Main app component

🔒 Security Features

• Rate Limiting: Prevents API abuse
• CORS Protection: Secure cross-origin requests
• Helmet: Security headers
• Input Validation: Sanitized user inputs
• Error Handling: Graceful error management

🚀 Deployment

Docker Deployment (Localhost-Only)

# Start all services with localhost-only access
docker compose up -d

# Start specific services
docker compose up -d mongodb hyperlogic-ai

# View logs
docker compose logs -f

# Stop all services
docker compose down

Environment Variables for Production

NODE_ENV=production
PORT=5000
GOOGLE_API_KEY=your_production_key
CORS_ORIGIN=https://yourdomain.com

Cloud Deployment

The application is ready for deployment on:

• Vercel: Frontend deployment
• Railway: Full-stack deployment
• Heroku: Backend deployment
• AWS or GCP: Scalable cloud deployment

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue on GitHub
• Check the documentation
• Review the troubleshooting guide

🔮 Roadmap

• Voice input/output support
• File upload and analysis
• Plugin system for custom providers
• Advanced conversation analytics
• Multi-language support
• Mobile app development

---

Built with ❤️ by HyperLogic AI Team