Spaces:
Configuration error
Configuration error
| # 🧮 MathGenius Academy | |
| An interactive Math Olympiad training platform powered by AI, designed to help students from Grade 1-10 master mathematics through adaptive learning and engaging challenges. | |
|  | |
|  | |
|  | |
| ## ✨ Features | |
| ### 🎯 **Adaptive Learning** | |
| - AI-generated questions tailored to grade level | |
| - Dynamic difficulty adjustment based on performance | |
| - Personalized learning paths for each student | |
| ### 📊 **Progress Tracking** | |
| - Comprehensive analytics and performance insights | |
| - Visual progress charts and trend analysis | |
| - Achievement badges and streak tracking | |
| ### 🎮 **Multiple Game Modes** | |
| - **Practice Mode**: Learn at your own pace with no time pressure | |
| - **Timed Mode**: Build speed and confidence with time challenges | |
| - **Challenge Mode**: Push your limits with advanced problems | |
| ### 🏆 **Achievement System** | |
| - Earn badges for various accomplishments | |
| - Track daily learning streaks | |
| - Celebrate milestones and improvements | |
| ### 🎨 **Clean UI Experience** | |
| - **No Streamlit Branding**: Clean, professional interface without logos or badges | |
| - **Light Mode Only**: Consistent light theme for optimal readability | |
| - Modern, responsive design with custom CSS | |
| - Intuitive navigation and user-friendly interface | |
| ## 🚀 How to Run the Application | |
| ### Prerequisites | |
| - Python 3.8 or higher | |
| - pip package manager | |
| - Groq API key (free at [console.groq.com](https://console.groq.com)) | |
| ### Local Development Setup | |
| 1. **Clone the repository** | |
| ```bash | |
| git clone https://github.com/Asgar-77/mathgenius-academy.git | |
| cd mathgenius-academy | |
| ``` | |
| 2. **Install dependencies** | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 3. **Set up your API key** | |
| - **Option 1 (Recommended)**: Set as environment variable | |
| ```bash | |
| export GROQ_API_KEY="your_groq_api_key_here" | |
| ``` | |
| - **Option 2**: The app will show setup instructions if no API key is found | |
| - **Get your free API key** at [console.groq.com](https://console.groq.com) | |
| 4. **Run the application** | |
| ```bash | |
| streamlit run app1.py | |
| ``` | |
| 5. **Open your browser** to `http://localhost:8501` | |
| ### Streamlit Cloud Deployment | |
| 1. **Upload** this repository to your GitHub account (no `.streamlit` folder needed!) | |
| 2. **Go to** [share.streamlit.io](https://share.streamlit.io) | |
| 3. **Connect** your GitHub repository | |
| 4. **Set main file** as: `app1.py` | |
| 5. **Add secrets** in Streamlit Cloud dashboard: | |
| - Go to App settings → Secrets | |
| - Add: `GROQ_API_KEY = "your_api_key_here"` | |
| 6. **Deploy** and enjoy your clean, unbranded app in light mode! | |
| **✅ Simplified Setup**: No configuration files needed - everything is embedded in the code! | |
| ## 🔧 Key Assumptions Made | |
| ### Technical Assumptions | |
| - **Internet Connection**: Required for AI question generation via Groq API | |
| - **Modern Browser**: Chrome, Firefox, Safari, or Edge for optimal experience | |
| - **JavaScript Enabled**: For interactive features and animations | |
| - **Screen Resolution**: Optimized for desktop (900x600+) but mobile-responsive | |
| ### Educational Assumptions | |
| - **Grade-Level Mapping**: Questions are mapped to typical curriculum standards | |
| - **English Language**: All content is in English (future multilingual support planned) | |
| - **Basic Math Knowledge**: Students should have foundational knowledge for their selected grade | |
| - **Self-Assessment**: Students can honestly select their appropriate grade level | |
| ### User Experience Assumptions | |
| - **Session-Based**: Progress is stored in browser session (no persistent accounts) | |
| - **Single User**: Designed for individual learning sessions | |
| - **Immediate Feedback**: Students benefit from instant question feedback | |
| - **Hint System**: Students will use hints constructively for learning | |
| ## 💡 Design Choices Explained | |
| ### Architecture Decisions | |
| #### **1. Streamlit Framework** | |
| - **Why**: Rapid development, built-in UI components, easy deployment | |
| - **Trade-off**: Less customization vs faster development | |
| - **Benefit**: Focus on educational content rather than web development | |
| #### **2. Groq API (Llama 3.3 70B)** | |
| - **Why**: Fast inference, high-quality question generation, cost-effective | |
| - **Alternative Considered**: OpenAI GPT-4 (more expensive, slower) | |
| - **Benefit**: Real-time question generation with excellent mathematical reasoning | |
| #### **3. Session State Management** | |
| - **Why**: Simple, no database required, immediate functionality | |
| - **Trade-off**: No persistence vs simplicity | |
| - **Future**: Will add database for user accounts and progress tracking | |
| ### UI/UX Design Choices | |
| #### **4. Branding Removal** | |
| - **Why**: Professional appearance, focus on content, white-label experience | |
| - **Implementation**: Custom CSS + Streamlit config to hide all branding | |
| - **Benefit**: Clean interface that looks like a dedicated educational platform | |
| #### **5. Light Mode Only** | |
| - **Why**: Better readability for mathematical content, consistent experience | |
| - **Implementation**: Forced light theme via config and CSS overrides | |
| - **Benefit**: Optimal contrast for equations and diagrams | |
| #### **6. Card-Based Layout** | |
| - **Why**: Modern design, clear content separation, mobile-friendly | |
| - **Implementation**: Custom CSS with gradients and shadows | |
| - **Benefit**: Engaging visual hierarchy that guides attention | |
| ### Educational Design Choices | |
| #### **7. Hint System** | |
| - **Why**: Scaffolded learning, reduces frustration, promotes understanding | |
| - **Implementation**: AI-generated hints for each question | |
| - **Benefit**: Students learn problem-solving strategies, not just answers | |
| #### **8. Multiple Difficulty Modes** | |
| - **Why**: Accommodates different learning styles and confidence levels | |
| - **Implementation**: Easy/Medium/Hard with different AI prompts | |
| - **Benefit**: Personalized challenge level for optimal learning zone | |
| #### **9. Progress Visualization** | |
| - **Why**: Motivates continued learning, shows improvement patterns | |
| - **Implementation**: Plotly charts with performance trends | |
| - **Benefit**: Data-driven insights into learning progress | |
| ## 🔮 Future Improvements | |
| ### Short-term Enhancements (Next 3 months) | |
| - [ ] **User Authentication**: Persistent accounts with Google/GitHub login | |
| - [ ] **Database Integration**: PostgreSQL for storing user progress and questions | |
| - [ ] **Enhanced Analytics**: Detailed performance breakdowns by topic | |
| - [ ] **Question Bank**: Pre-generated question cache for faster loading | |
| - [ ] **Mobile App**: React Native version for offline practice | |
| - [ ] **Accessibility**: Screen reader support, keyboard navigation | |
| - [ ] **Internationalization**: Spanish, French, and Hindi language support | |
| ### Medium-term Features (3-6 months) | |
| - [ ] **Social Learning**: Study groups, peer challenges, leaderboards | |
| - [ ] **Teacher Dashboard**: Classroom management, student progress monitoring | |
| - [ ] **Advanced AI**: GPT-4 integration for more sophisticated questions | |
| - [ ] **Adaptive Algorithms**: Machine learning for personalized difficulty | |
| - [ ] **Content Expansion**: Physics, Chemistry, and Science questions | |
| - [ ] **Gamification**: XP system, achievements, virtual rewards | |
| - [ ] **Offline Mode**: Downloadable question packs for offline practice | |
| ### Long-term Vision (6+ months) | |
| - [ ] **AI Tutoring**: Conversational AI for step-by-step problem solving | |
| - [ ] **Video Explanations**: AI-generated video solutions for complex problems | |
| - [ ] **Curriculum Integration**: Alignment with Common Core, IB, and other standards | |
| - [ ] **Parent Portal**: Progress reports, learning recommendations | |
| - [ ] **Advanced Analytics**: Predictive modeling for learning outcomes | |
| - [ ] **VR/AR Integration**: Immersive 3D mathematical visualizations | |
| - [ ] **Marketplace**: User-generated content, teacher-created question sets | |
| ### Technical Improvements | |
| - [ ] **Performance Optimization**: Redis caching, CDN integration | |
| - [ ] **Microservices Architecture**: Separate services for AI, analytics, user management | |
| - [ ] **Real-time Features**: WebSocket integration for live collaboration | |
| - [ ] **Advanced Security**: OAuth 2.0, rate limiting, input sanitization | |
| - [ ] **Monitoring**: Application performance monitoring, error tracking | |
| - [ ] **Testing**: Comprehensive unit tests, integration tests, E2E testing | |
| - [ ] **CI/CD Pipeline**: Automated testing, deployment, and rollback procedures | |
| ## 🛠️ Technology Stack | |
| - **Frontend**: Streamlit with custom CSS styling | |
| - **AI Engine**: Groq API (Llama 3.3 70B Versatile) | |
| - **Data Visualization**: Plotly, Pandas | |
| - **Deployment**: Streamlit Community Cloud | |
| - **Language**: Python 3.8+ | |
| - **Configuration**: TOML for settings, environment variables for secrets | |
| ## 📚 Grade Level Coverage | |
| | Grade Range | Age Group | Topics Covered | | |
| |-------------|-----------|----------------| | |
| | **Grades 1-4** | Ages 6-10 | Basic arithmetic, counting, simple word problems, pattern recognition | | |
| | **Grades 5-8** | Ages 10-14 | Pre-algebra, fractions, decimals, basic statistics, coordinate geometry | | |
| | **Grades 9-10** | Ages 14-16 | Advanced algebra, geometry proofs, trigonometry, complex problem solving | | |
| ## 🔒 Security & Privacy | |
| - **API Keys**: Stored securely using Streamlit secrets management | |
| - **No Data Collection**: No personal information stored or transmitted | |
| - **Input Validation**: All user inputs are sanitized and validated | |
| - **Secure Deployment**: HTTPS encryption, secure headers | |
| - **Privacy First**: No tracking, analytics, or third-party data sharing | |
| ## 📈 Performance Features | |
| - **Smart Caching**: Question generation results cached for faster loading | |
| - **Responsive Design**: Optimized for desktop, tablet, and mobile devices | |
| - **Lazy Loading**: Resources loaded on-demand for faster initial page load | |
| - **Error Handling**: Graceful degradation with helpful error messages | |
| - **Offline Fallback**: Basic functionality available without internet | |
| ## 🤝 Contributing | |
| We welcome contributions! Please follow these steps: | |
| 1. **Fork** the repository | |
| 2. **Create** a feature branch (`git checkout -b feature/amazing-feature`) | |
| 3. **Commit** your changes (`git commit -m 'Add amazing feature'`) | |
| 4. **Push** to the branch (`git push origin feature/amazing-feature`) | |
| 5. **Open** a Pull Request | |
| ### Development Guidelines | |
| - Follow PEP 8 style guidelines | |
| - Add docstrings to all functions | |
| - Include unit tests for new features | |
| - Update documentation as needed | |
| ## 📄 License | |
| This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. | |
| ## 🙏 Acknowledgments | |
| - **Groq** for providing fast and reliable AI infrastructure | |
| - **Streamlit** for the amazing web framework that makes Python web apps simple | |
| - **Plotly** for beautiful, interactive data visualizations | |
| - **Math educators worldwide** for inspiration and pedagogical insights | |
| - **Open source community** for tools and libraries that make this possible | |
| ## 📞 Support & Contact | |
| If you encounter any issues or have questions: | |
| 1. **Check Documentation**: Review this README and deployment guides | |
| 2. **Search Issues**: Look through existing GitHub issues | |
| 3. **Create Issue**: Open a new issue with detailed description | |
| 4. **Email Support**: Contact us at [your-email@domain.com] | |
| ### Common Issues | |
| - **API Key Errors**: Ensure your Groq API key is valid and properly set | |
| - **Deployment Issues**: Check Streamlit Cloud logs for detailed error messages | |
| - **Performance**: Clear browser cache and refresh the application | |
| ## 🎯 Project Status | |
| - ✅ **Core Features**: Complete and functional | |
| - ✅ **UI/UX**: Modern design with branding removal | |
| - ✅ **AI Integration**: Groq API fully integrated | |
| - ✅ **Deployment Ready**: Streamlit Cloud compatible | |
| - 🔄 **Active Development**: Regular updates and improvements | |
| - 📋 **Roadmap**: Detailed future enhancement plans | |
| --- | |
| **Made with ❤️ for young mathematicians everywhere!** | |
| *Empowering the next generation of problem solvers through interactive, AI-powered learning.* | |
| **Repository**: [https://github.com/Asgar-77/mathgenius-academy](https://github.com/Asgar-77/mathgenius-academy) |