🧠 Universal Learning Engine (ULE) - Adaptive learning for any subject

Version 1.0 Created by Ryan Rustill

A sophisticated, open-source adaptive learning system that teaches fundamental concepts through systematic analysis. Built with an advanced educational algorithms that adapt to individual learning patterns.

🌟 What Makes This Special

This isn't just another quiz system - it's an intelligent adaptive learning engine that:

• 🧠 Learns from your performance and adjusts question difficulty in real-time
• 🎯 Focuses on weak areas while challenging your strengths
• ♾️ Never repeats questions so you can return for continuous learning
• 📚 Teaches systematic thinking through the "Detective Method"
• 💾 Remembers your progress across sessions with automatic save/load
• 🔍 Provides detailed explanations for every single answer

🎯 The Detective Method

This system teaches you to approach code like a detective:

1. Read the code line by line
2. Track what each variable contains
3. Follow the execution order
4. Think about what each operation does
5. Predict the final result
6. Double-check your logic

🚀 Quick Start

# Clone the repository
git clone https://github.com/RyanRustill/universal-learning-engine.git
cd universal-learning-engine

# Launch the universal learning system
python3 ule.py

That's it! The system will automatically discover available subjects and guide you through your adaptive learning journey.

🎯 Universal Learning Platform

ULE features a universal launcher that automatically discovers and presents all available learning subjects:

• 🔍 Automatic Discovery - Scans the subjects/ directory for new learning modules
• 📋 Clean Menu Interface - Simple numbered menu for subject selection
• 🔄 Seamless Navigation - Easy return to main menu from any subject
• 📚 Extensible Design - Add new subjects by simply dropping modules in subjects/

The system intelligently finds any subject module with standard naming patterns (rrle_[subject].py, launcher.py, etc.) and makes them instantly available.

🧠 Adaptive Learning Features

Dynamic Difficulty Adjustment

• Questions get harder when you master concepts (80%+ success rate)
• Questions get easier when you struggle (30% or lower success rate)
• Each concept has individual difficulty tracking (1-5 stars ⭐)

Intelligent Question Selection

• Prioritizes concepts where you need practice
• Ensures diverse question variety each round
• Balances challenge with learning opportunities
• Tracks everything you've seen to avoid repeats

Progress Persistence

• Automatically saves progress between sessions
• Real-time difficulty levels for each concept
• Success rates and mastery indicators
• Comprehensive learning analytics

📚 Currently Available Subjects

Python Fundamentals

The system covers fundamental Python concepts across 5 difficulty levels:

• Variable Assignment - Basic storage, calculations, complex logic
• String Indexing - Positive/negative indexing, dynamic access
• List Operations - Manipulation, methods, comprehensions
• Data Types - Numbers, strings, booleans, type conversion
• Control Flow - Loops, conditionals, logical operators

Each concept includes 25 carefully crafted questions (125+ total) designed to support 20+ rounds of learning without repetition.

Mathematics (Proof of Concept)

Demonstrates the extensibility with core mathematical concepts:

• Arithmetic - Basic operations and mental math
• Algebra - Variable solving and substitution
• Word Problems - Real-world mathematical scenarios
• Fractions - Addition and multiplication with fractions
• Geometry - Shapes, areas, and angle calculations

Note: Mathematics is intentionally kept minimal (13 questions across 3 difficulty levels) as a proof-of-concept and template for community contributions. It demonstrates the complete integration process while inviting others to expand upon the foundation.

🏗️ Technical Architecture

Core Classes

• ULE - The main adaptive learning engine
• DifficultyManager - Handles adaptive difficulty progression
• AdaptiveQuestionSelector - Intelligently chooses questions
• UniversalUI - Beautiful terminal interface with colors

Key Features

• Universal Design - Core algorithms work for any subject
• Dataclass-based question and performance tracking
• Deque-based recent performance analysis (last 3 attempts)
• JSON-based question database for easy expansion
• Color-coded terminal output for enhanced experience

📊 Understanding Your Progress

Difficulty Indicators

• ⭐ (Level 1): Basic fundamentals
• ⭐⭐ (Level 2): Building understanding
• ⭐⭐⭐ (Level 3): Intermediate concepts
• ⭐⭐⭐⭐ (Level 4): Advanced applications
• ⭐⭐⭐⭐⭐ (Level 5): Expert level challenges

Mastery Status

• 🏆 MASTERED (85%+ success rate)
• 📈 PROFICIENT (70-84% success rate)
• 📚 DEVELOPING (50-69% success rate)
• 🧠 LEARNING (Below 50% - focused practice mode)

🔄 Adaptive Learning Algorithm

The system uses sophisticated algorithms to:

1. Track recent performance (sliding window of last 3 attempts)
2. Calculate success rates (both overall and recent trends)
3. Identify struggling concepts for additional practice
4. Balance question selection between reinforcement and exploration
5. Adjust difficulty dynamically based on demonstrated mastery

📁 Project Structure

universal-learning-engine/
├── ule.py                      # 🚀 Universal launcher (main entry point)
├── engine/                     # Core ULE adaptive learning engine
│   ├── core/                  # Universal algorithms
│   │   └── adaptive_engine.py # Main learning engine classes
│   ├── ui/                    # Terminal interface
│   │   └── terminal_ui.py     # Beautiful color-coded UI
│   └── modules/               # Subject-specific implementations
│       ├── python.py          # Python subject module
│       └── mathematics.py     # Mathematics subject module
├── subjects/                   # Individual subject modules
│   ├── python/                # Python learning module
│   │   ├── ule_python.py             # Python launcher
│   │   └── python_questions.json     # Python question database (125 questions)
│   └── mathematics/           # Mathematics learning module
│       ├── ule_mathematics.py        # Mathematics launcher
│       └── mathematics_questions.json # Math question database (13 questions)
├── tests/                     # 🧪 Comprehensive testing infrastructure
│   ├── run_tests.py          # Professional test runner with beautiful output
│   ├── test_core_engine.py   # Core engine unit tests (24 tests)
│   ├── test_ui.py            # User interface tests (16 tests)
│   ├── analyze_questions.py  # Interactive question database analyzer
│   └── README.md             # Testing documentation and guidelines
|── ABOUT.md                  # Project origin story
├── EXTENDIBILITY.md          # 🚀 Complete step-by-step extension guide
└── README.md                 # This documentation

🧪 Testing & Quality Assurance

ULE includes a comprehensive testing infrastructure to ensure reliability and quality:

🚀 Quick Testing

# Run all tests with beautiful output
python3 tests/run_tests.py

# Run specific test categories
python3 -m unittest tests.test_core_engine -v    # Core engine tests
python3 -m unittest tests.test_ui -v             # User interface tests

# Analyze question databases interactively
python3 tests/analyze_questions.py               # Interactive subject selection
python3 tests/analyze_questions.py python        # Analyze Python only
python3 tests/analyze_questions.py --summary     # Quick overview

🔍 Question Database Analyzer

The interactive question analyzer helps developers and educators assess question quality:

python3 tests/analyze_questions.py

Features:

• 🎯 Interactive Menu - Choose specific subjects or analyze all
• 📊 Quality Assessment - Automatic evaluation of question databases
• 📈 Analytics - Difficulty distribution, concept coverage, learning potential
• 🎮 Adaptive Metrics - Estimates replay value and learning effectiveness
• 💡 Recommendations - Suggestions for improving question sets

Sample Output:

🎯 AVAILABLE SUBJECTS (2 found):
==================================================
  1. Mathematics
  2. Python  
  A. All Subjects
  S. Summary Table Only
  Q. Quit

👉 Select subjects to analyze (e.g., 1,3 or A for all): 2

📊 PYTHON QUESTION DATABASE ANALYSIS
======================================================================
📊 OVERVIEW:
   Subject: Python
   Total Questions: 125
   Concepts: 5
   Difficulty Levels: 1-5
   
🌟 DATABASE QUALITY ASSESSMENT:
   ✅ Sufficient question volume
   ✅ Good concept diversity
   ✅ Multi-level difficulty
   ✅ Well-balanced difficulty distribution

🧪 Test Coverage

Core Engine Tests (24 tests):

• ✅ Question dataclass functionality
• ✅ Difficulty management and adaptation
• ✅ Adaptive question selection algorithms
• ✅ Progress saving and loading
• ✅ Session management
• ✅ Integration testing with multiple rounds

UI Tests (16 tests):

• ✅ Terminal interface functionality
• ✅ Color-coded output validation
• ✅ User input handling
• ✅ Menu navigation
• ✅ Subject configuration

Quality Metrics:

• 📊 40 total tests with 95%+ success rate
• 🔍 Comprehensive coverage of all core functionality
• 🚀 Performance testing for question selection efficiency
• 🧩 Integration tests for complete learning scenarios

🛠️ For Developers

When contributing code or question sets:

# Always run tests before submitting
python3 tests/run_tests.py

# Analyze your question database
python3 tests/analyze_questions.py your_subject

# Check specific functionality
python3 -m unittest tests.test_core_engine.TestULE -v

The testing framework ensures:

• No question repetition within sessions
• Proper difficulty adaptation based on performance
• Reliable progress persistence across sessions
• Quality question selection for optimal learning

🎯 Perfect For

• Students learning programming fundamentals
• Self-taught learners practicing for exams or assignments
• Educational institutions looking for adaptive learning tools
• Anyone wanting to strengthen systematic reasoning skills

🚀 Educational Philosophy

This tool embodies the belief that adaptive learning is more effective than one-size-fits-all approaches. By adjusting to individual pace and focusing on specific needs, it maximizes learning efficiency while maintaining motivation.

The "Detective Method" teaches systematic analysis - a skill that transfers to debugging, code review, and learning new concepts throughout your career.

🔬 Technical Innovation

Adaptive Algorithms

• 3-attempt sliding window for recent performance tracking
• Concept-specific difficulty scaling (1-5 levels per concept)
• Intelligent question distribution ensuring variety and focus
• Session persistence with JSON-based progress storage

Universal Design

• Subject-agnostic core - easily extensible to other subjects and programming languages
• Modular architecture - clean separation between engine and content
• Flexible content format - JSON schema supports various question types

🌟 Inspiration

This project began as a simple Python quiz in my learning snippets. When a community member improved my initial code, I realized I could build something much more sophisticated.

This adaptive learning engine demonstrates advanced programming concepts while solving real educational challenges. The universal architecture shows how sophisticated educational technology can be built with clean, extensible code.

📈 Future Development

The modular architecture makes it easy to add:

• New programming languages (JavaScript, Java, C++, etc.)
• Additional subjects (Mathematics, Logic, Science, etc.)
• Different question types (debugging, code completion, etc.)
• Enhanced analytics and progress visualization

Want to add your own subject? See EXTENDIBILITY.md for a complete step-by-step guide using Mathematics as a real example.

🤝 Contributing

This is an open source educational project. Contributions are welcome, especially:

• New question sets following the JSON schema
• Additional subjects as new modules (see EXTENDIBILITY.md)
• Enhanced UI features for better learning experience
• Educational improvements to explanations and methodology

The universal launcher makes adding new subjects incredibly easy - just follow the step-by-step guide and your subject appears automatically in the main menu!

All contributions remain under the MIT license, meaning they stay free and open for the community to use, modify, and extend.

🔒 Note: ULE is a standalone open-source project. Any features or ideas that overlap with the upcoming mobile platform ReasonRoot will be implemented independently. Community contributions to ULE will not be reused commercially without permission or attribution.

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• @DoctorChocolat - For pioneering the JSON-based question format that inspired this implementation. Their refactored version introduced the concept of separating questions into JSON files, which became foundational to the adaptive learning engine's design.
• Inspired by community feedback on initial implementation
• Built with educational psychology principles
• Designed for real learning outcomes, not just engagement

---

Ready to master learning through systematic reasoning? 🚀

python3 ule.py

Created by @RyanRustill