🤖 Tomas SM Bautista Elementary School Chatbot

A sophisticated, multilingual AI chatbot designed specifically for Tomas SM Bautista Elementary School. Built with FastAPI, Supabase, and advanced NLP technologies, it provides intelligent responses to school-related queries in English, Tagalog, and Aklanon.

🌟 Features

🧠 Advanced AI Capabilities

• Multi-Provider AI Support: Groq, Cohere, and Hugging Face with intelligent fallback
• Context-Aware Responses: Remembers conversation history and user information
• Smart Query Processing: Handles complex, multi-part questions intelligently
• Intent Classification: Advanced NLU engine with 15+ intent categories
• Entity Extraction: Automatically extracts names, grades, and relationships

🌍 Multilingual Support

• English: Primary language with full support
• Tagalog: Complete Filipino language support
• Aklanon: Regional language support for Aklan province
• Automatic Language Detection: Detects and responds in the appropriate language
• Language Consistency: Ensures responses match the detected input language

🔍 Advanced Search & Retrieval

• Three-Tier Search System: Combines FTS, BM25, and Smart Fuzzy search
• Semantic Search: Context-aware information retrieval
• Connection Pooling: Optimized Supabase database connections
• Intelligent Caching: Redis and in-memory caching for performance
• Smart Scoring: Dynamic relevance scoring for accurate results

💬 Conversational Intelligence

• Simple Response Handling: Context-aware responses to "yes", "no", "help", etc.
• Vague Query Suggestions: Provides helpful suggestions for unclear queries
• Elongated Greeting Support: Recognizes "hiiii", "hellooo", "heyyy" as greetings
• Multi-Question Detection: Handles complex queries with multiple questions
• Conversation Memory: Remembers user information across sessions

🛡️ Security & Performance

• Input Validation: Comprehensive security checks and sanitization
• Rate Limiting: Prevents abuse and ensures fair usage
• Error Handling: Graceful error recovery and user-friendly messages
• Performance Monitoring: Real-time system health and performance tracking
• Typo Correction: Automatically corrects common spelling mistakes

🏗️ Architecture

Core Components

├── chatbot_refactored.py          # Main chatbot orchestrator
├── nlu_engine.py                  # Natural Language Understanding
├── core/
│   ├── database_search.py        # Database search engine
│   ├── three_tier_search.py      # Advanced search system
│   ├── language_detector.py       # Multilingual detection
│   ├── conversation_memory.py    # Context retention
│   ├── response_generator.py     # AI response generation
│   ├── optimized_nlu_engine.py   # Performance-optimized NLU
│   └── supabase_pool.py          # Connection pooling
├── entity_extractor.py           # Named entity recognition
└── app.py                        # FastAPI application

Technology Stack

• Backend: FastAPI + Python 3.9+
• Database: Supabase (PostgreSQL) with connection pooling
• AI Providers: Groq, Cohere, Hugging Face
• NLP: NLTK, TextBlob, custom regex patterns
• Caching: Redis + in-memory caching
• Deployment: Heroku, Render

🚀 Quick Start

Prerequisites

• Python 3.9 or higher
• Supabase account and project
• AI provider API keys (Groq, Cohere, or Hugging Face)

Installation

1. Clone the repository

git clone <repository-url>
cd TomasChatBot

2. Create virtual environment

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

3. Install dependencies

pip install -r requirements.txt

4. Set up environment variables Create a .env file with:

# Supabase Configuration
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_anon_key

# AI Provider Keys (at least one required)
GROQ_API_KEY=your_groq_api_key
COHERE_API_KEY=your_cohere_api_key
HUGGINGFACE_API_KEY=your_huggingface_api_key

# Optional: Redis for caching
REDIS_URL=your_redis_url

5. Run the application

python app.py

The chatbot will be available at http://localhost:8000

🧪 Testing

Interactive Testing

Use the built-in web interface for interactive testing:

# Start the test server
python Hidden_Files/start_server.py

# Access the chat interface
open http://localhost:8000

Automated Testing

Run comprehensive test suites:

# Feature matrix test
python Hidden_Files/chatbot_feature_matrix.py

# Comprehensive test suite
python comprehensive_chatbot_test.py

# Performance benchmark
python performance_benchmark.py

Test Categories

• ✅ Core Functionality: Intent classification, entity extraction
• ✅ Multilingual Support: English, Tagalog, Aklanon
• ✅ Conversation Memory: Context retention across messages
• ✅ Advanced Features: Multi-question handling, vague query suggestions
• ✅ Performance: Response times, caching efficiency
• ✅ Security: Input validation, rate limiting

📊 Usage Examples

Basic Queries

# Initialize chatbot
from chatbot_refactored import ChatBot
chatbot = ChatBot('your_api_key')

# Simple greeting
response = await chatbot.chat("Hello", session_id="user123")
# Response: "Hello! Welcome to Tomas SM Bautista Elementary School..."

# Teacher inquiry
response = await chatbot.chat("Who is the teacher for grade 1?", session_id="user123")
# Response: "For Grade 1, the adviser is Mrs. Annalyn B. She teaches..."

# School hours
response = await chatbot.chat("What are the school hours?", session_id="user123")
# Response: "Our school hours are from 7:00 AM to 5:00 PM..."

Multilingual Queries

# Tagalog query
response = await chatbot.chat("Sino ang principal?", session_id="user123")
# Response: "Walang principal pa pero ang Head Teacher ay si Meliza A. Delgado..."

# Aklanon query
response = await chatbot.chat("Sin-o ang guro sa Grade 1?", session_id="user123")
# Response: "Sa Grade 1, ang adviser ay si Mrs. Annalyn B..."

Complex Queries

# Multiple questions
response = await chatbot.chat("Who is the teacher for grade 1 and 5?", session_id="user123")
# Response: "For Grade 1, the adviser is Mrs. Annalyn B. For Grade 5..."

# Context-aware responses
await chatbot.chat("My daughter is in grade 4", session_id="user123")
response = await chatbot.chat("What grade is my daughter in?", session_id="user123")
# Response: "Your daughter is in Grade 4..."

🔧 Configuration

Environment Variables

Variable	Description	Required
SUPABASE_URL	Supabase project URL	Yes
SUPABASE_KEY	Supabase anon key	Yes
GROQ_API_KEY	Groq API key	At least one
COHERE_API_KEY	Cohere API key	At least one
HUGGINGFACE_API_KEY	Hugging Face API key	At least one
REDIS_URL	Redis connection URL	No

Customization

• Response Templates: Modify core/response_generator.py
• Language Patterns: Update core/language_detector.py
• Intent Classification: Extend nlu_engine.py
• Database Schema: Modify Supabase tables and prompts

🚀 Deployment

Heroku Deployment

# Deploy to Heroku
heroku login
heroku create tomas-chatbot
git push heroku main

Render Deployment

# Deploy to Render
# Configure via Render dashboard with:
# - Build Command: pip install -r requirements.txt
# - Start Command: python app.py

📈 Performance

Benchmarks

• Response Time: < 2 seconds average
• Throughput: 100+ concurrent users
• Accuracy: 95%+ intent classification
• Cache Hit Rate: 80%+ for repeated queries

Optimization Features

• Connection Pooling: Efficient database connections
• Multi-Level Caching: Redis + in-memory caching
• Async Processing: Non-blocking I/O operations
• Smart Chunking: Optimal response splitting

🛠️ Development

Project Structure

TomasChatBot/
├── core/                    # Core modules
│   ├── database_search.py   # Database operations
│   ├── nlu_engine.py       # Natural language processing
│   ├── language_detector.py # Multilingual support
│   └── ...
├── templates/              # HTML templates
├── nltk_data/             # NLTK language data
├── Hidden_Files/          # Server and testing files
├── config/                # Configuration files
├── requirements.txt       # Python dependencies
├── app.py                 # Main application
└── chatbot_refactored.py  # Core chatbot logic

Adding New Features

1. New Intent: Add patterns to nlu_engine.py
2. New Language: Extend language_detector.py
3. New Response Type: Modify response_generator.py
4. New Search Method: Extend database_search.py

Code Quality

• Type Hints: Full type annotation coverage
• Error Handling: Comprehensive exception handling
• Logging: Structured logging throughout
• Testing: Automated test suites for all features

🐛 Troubleshooting

Common Issues

1. Import Errors

   # Ensure virtual environment is activated
   source .venv/bin/activate
   pip install -r requirements.txt

2. Database Connection Issues

   # Check Supabase credentials
   echo $SUPABASE_URL
   echo $SUPABASE_KEY

3. AI Provider Errors

   # Verify API keys
   echo $GROQ_API_KEY
   echo $COHERE_API_KEY

4. NLTK Data Issues

   # Download required NLTK data
   python -c "import nltk; nltk.download('punkt'); nltk.download('averaged_perceptron_tagger')"

Debug Mode

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

📚 API Documentation

Main Endpoints

• POST /chat - Send message to chatbot
• GET /health - Health check
• GET /docs - Interactive API documentation

Request Format

{
  "query": "Who is the teacher for grade 1?",
  "session_id": "user123",
  "conversation_history": []
}

Response Format

{
  "response": ["For Grade 1, the adviser is Mrs. Annalyn B..."],
  "intent": "staff_inquiry",
  "entities": [{"type": "grade", "value": "1"}],
  "detected_language": "en",
  "language_confidence": 0.95
}

🤝 Contributing

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

Development Guidelines

• Follow PEP 8 style guidelines
• Add type hints to all functions
• Include comprehensive docstrings
• Write tests for new features
• Update documentation as needed

📄 License

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

🙏 Acknowledgments

• Tomas SM Bautista Elementary School for providing the educational context
• Supabase for the excellent backend-as-a-service platform
• Groq, Cohere, and Hugging Face for AI provider services
• FastAPI for the robust web framework
• NLTK for natural language processing capabilities

📞 Support

For support and questions:

• Create an issue in the repository
• Check the troubleshooting section
• Review the API documentation
• Test with the interactive interface

---

Built with ❤️ for Tomas SM Bautista Elementary School