🚀 ULE Extendibility Guide - Adding New Learning Subjects

Universal Learning Engine (ULE) is designed to be infinitely extensible. Adding a new learning subject takes just a few steps and requires no modifications to the core engine.

This guide walks you through the complete process using Mathematics as a real example.

✨ The Magic: Automatic Discovery

ULE's Universal Launcher automatically discovers new subjects. Simply follow the naming convention and your subject appears instantly in the main menu - no configuration files to edit!

📋 Complete Step-by-Step Guide

Step 1: Create Subject Directory Structure

# Navigate to your ULE root directory
cd universal-learning-engine/

# Create the new subject directory
mkdir -p subjects/mathematics

The subjects/ directory is where all learning modules live. Each subject gets its own subdirectory.

Step 2: Create the Question Database

Create subjects/mathematics/mathematics_questions.json:

[
    {
        "concept": "arithmetic", 
        "difficulty": 1,
        "questions": [
            {
                "id": "math_001",
                "problem": "If you have 15 apples and eat 7 of them, how many apples do you have left?",
                "options": [
                    "A) 6",
                    "B) 8", 
                    "C) 9", 
                    "D) 22"
                ],
                "correct": "B",
                "explanation": "This is basic subtraction: 15 - 7 = 8. When you remove 7 apples from 15, you're left with 8 apples."
            }
            // ... more questions
        ]
    }
    // ... more concepts and difficulties
]

Key Requirements:

Each concept group has concept, difficulty, and questions array
Each question needs id, problem/code/scenario, options, correct, explanation
Use descriptive IDs and clear explanations for maximum learning impact

Step 3: Create the Engine Module

Create engine/modules/mathematics.py:

# 🧠 ULE Mathematics Module - Mathematical Reasoning & Problem Solving
# Mathematics implementation using Universal Learning Engine
# Created by Ryan Rustill

import json
import os
from typing import List, Optional
from ..core.adaptive_engine import ULE, Question
from ..ui.terminal_ui import UniversalUI, MATH_CONFIG, Colors

class MathematicsQuestionLoader:
    """Loads and converts mathematics questions for ULE"""
    
    @staticmethod
    def load_from_json(filepath: str) -> List[Question]:
        # Convert subject-specific JSON to universal Question format
        # Handle file loading, error checking, JSON parsing
        # Return list of Question objects

class MathematicsLearningSession:
    """Complete mathematics learning session using ULE"""
    
    def __init__(self, questions_file=None, progress_file="mathematics_progress.json"):
        # Load questions, initialize ULE engine, set up UI
        
    def run(self):
        # Main learning loop with adaptive rounds
        # Handle menu navigation and progress saving
        # Return 'menu' or 'exit' for universal launcher

def main():
    """Entry point for Mathematics learning module"""
    # Handle session creation, keyboard interrupts, return codes

Key Patterns:

Follow the same structure as engine/modules/python.py
Use MATH_CONFIG from terminal UI (or create your own)
Return 'menu' or 'exit' from run() for navigation
Handle progress saving with unique filename

Step 4: Create the Subject Launcher

Create subjects/mathematics/ule_mathematics.py:

#!/usr/bin/env python3
# 🧠 ULE Mathematics Learning - Main Launcher
# ULE Mathematics Module Entry Point
# Created by Ryan Rustill

import sys
import os

# Add the root ULE directory to Python path (go up 2 levels from subjects/mathematics/)
ule_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
sys.path.insert(0, ule_root)

from engine.modules.mathematics import main

if __name__ == "__main__":
    print("🧠 Universal Learning Engine - Mathematics Module")
    print("Loading adaptive learning system...")
    print()
    sys.exit(main())

Critical Details:

Naming Convention: ule_[subject].py for automatic discovery
Path Setup: Navigate correctly to add ULE root to Python path
Import: Reference your engine module
Exit Code: Use sys.exit(main()) for proper return codes

Step 5: Make Executable (Optional but Recommended)

chmod +x subjects/mathematics/ule_mathematics.py

Step 6: Test the Magic! 🎉

# Launch the universal system
python3 ule.py

Your new subject automatically appears in the menu:

======================================================================
🧠 UNIVERSAL LEARNING ENGINE (ULE)
Adaptive learning for any subject
Created by Ryan Rustill
======================================================================

🎯 AVAILABLE LEARNING SUBJECTS:

1. Python
   Master Python fundamentals through code analysis

2. Mathematics  ← ✨ Automatically discovered!
   Learn Mathematics concepts

Q. Quit ULE

🎯 Subject Configuration Options

Customize your learning experience by creating a subject config in engine/ui/terminal_ui.py:

MATH_CONFIG = SubjectConfig(
    name="Mathematics",
    title="Mathematical Reasoning Mastery",
    method_name="Problem-Solving Method",
    method_steps=[
        "Identify what's being asked",
        "Note all given information", 
        "Choose the right approach",
        "Work through step-by-step",
        "Check your answer makes sense",
        "Verify with different method if possible"
    ],
    content_label="Solve this problem:",
    content_formatter=lambda content: content.get('problem', str(content))
)

Or use existing configs: PYTHON_CONFIG, MATH_CONFIG, LOGIC_CONFIG

🔧 Advanced Customization

Custom Content Types

The content field in questions is flexible. Examples:

# For code-based subjects
content = {'code': 'x = 5\nprint(x + 3)'}

# For math problems  
content = {'problem': 'What is 2 + 2?'}

# For logic scenarios
content = {'scenario': 'If all birds can fly, and penguins are birds...'}

# For complex problems
content = {
    'problem': 'Calculate the area',
    'diagram': 'triangle.png',
    'given': ['base = 10cm', 'height = 8cm']
}

Custom Question Types

Beyond multiple choice, you could extend for:

Fill-in-the-blank
Code completion
Debugging exercises
Multi-step problems

Progress File Naming

Use unique progress files to prevent conflicts:

progress_file = "mathematics_progress.json"  # ✅ Good
progress_file = "progress.json"              # ❌ Conflicts

📋 Naming Conventions for Discovery

The Universal Launcher looks for these patterns (in order):

ule_[subject].py ← Recommended
[subject]_ule.py
launcher.py
main.py

Examples:

ule_mathematics.py ✅
ule_javascript.py ✅
ule_chemistry.py ✅
mathematics_ule.py ✅ (also works)

🎯 Subject Ideas to Inspire You

Programming Languages

JavaScript - Web development fundamentals
Java - Object-oriented programming
C++ - Memory management and pointers
SQL - Database queries and design

Academic Subjects

Physics - Problem-solving with formulas
Chemistry - Balancing equations and reactions
Biology - Classification and processes
History - Timeline reasoning and cause/effect

Professional Skills

Logic - Formal reasoning and proofs
Statistics - Data analysis and interpretation
Finance - Investment calculations and concepts
Design - Color theory and composition

🚀 Community Contribution

Perfect First Contribution: Expand Mathematics! 🧮

The Mathematics module is intentionally minimal and perfect for your first contribution:

Add more arithmetic problems (multiplication tables, order of operations)
Expand algebra (quadratic equations, systems of equations)
Include advanced geometry (circles, triangles, coordinate geometry)
Add calculus basics (derivatives, integrals)
Create statistics and probability sections

For New Subjects

Start Small - 10-15 questions across 2-3 concepts
Focus on Fundamentals - Cover core concepts thoroughly
Educational Explanations - Each answer should teach something
Test Thoroughly - Ensure adaptive difficulty works well

For Existing Subjects

Add Question Variations - More practice for existing concepts
New Difficulty Levels - Extend the 1-5 scale if needed
Improved Explanations - Make learning even clearer
Bug Fixes - Report and fix any issues

💡 Tips for Success

Question Design

Clear and Unambiguous - Avoid trick questions
Educational Focus - Prioritize learning over difficulty
Balanced Options - Avoid patterns in correct answers
Real-World Context - Use practical examples when possible

Concept Organization

Logical Progression - Easy to hard within each concept
Distinct Concepts - Clear separation between different topics
Appropriate Difficulty - Match complexity to difficulty level
Comprehensive Coverage - Hit all important fundamentals

Testing Your Subject

ULE includes comprehensive testing infrastructure to ensure quality:

# Test the launcher directly
cd subjects/your_subject
python3 ule_your_subject.py

# Test through universal launcher
cd ../../
python3 ule.py
# Select your subject and play several rounds

# 🧪 QUALITY ASSURANCE (Essential!)
# Analyze your question database for quality
python3 tests/analyze_questions.py your_subject

# Run the complete test suite
python3 tests/run_tests.py

# Test core functionality specifically
python3 -m unittest tests.test_core_engine -v

Quality Checklist:

✅ Interactive Analysis: Use the question analyzer to get quality metrics
✅ "GOOD" Rating: Aim for 25+ questions with balanced difficulty distribution
✅ All Tests Pass: Ensure the test suite shows 40/40 passing tests
✅ No Regression: Verify existing subjects still work properly

Sample Quality Report:

📊 YOUR_SUBJECT QUESTION DATABASE ANALYSIS
======================================================================
📊 OVERVIEW:
   Subject: Your Subject
   Total Questions: 25
   Concepts: 4
   Difficulty Levels: 1-3
   
🌟 DATABASE QUALITY ASSESSMENT:
   ✅ Sufficient question volume
   ✅ Good concept diversity
   ✅ Multi-level difficulty
   ⚠️  Consider balancing difficulty levels  ← Fix this!

The question analyzer provides specific recommendations for improving your question database. Always run it before submitting contributions!

🎉 The Result

When you follow this guide, you get:

✅ Automatic Discovery - Appears instantly in main menu
✅ Full ULE Power - Adaptive difficulty, progress tracking, analytics
✅ Seamless Navigation - Return to menu between subjects
✅ Session Persistence - Progress saved across restarts
✅ Professional UI - Beautiful terminal interface with colors
✅ Zero Configuration - No files to edit, no hardcoded lists

🌟 Real-World Example

This entire guide is based on the Mathematics subject that was added to ULE in under 60 minutes. It demonstrates:

5 mathematical concepts (arithmetic, algebra, word problems, fractions, geometry)
13 carefully crafted questions with educational explanations
3 difficulty levels showing adaptive progression
Complete integration with universal launcher and navigation
Progress persistence with unique file naming

Intentionally Minimal: The Mathematics module is kept deliberately small as a proof-of-concept and invitation for community expansion. It shows the complete integration process without overwhelming new contributors, making it an ideal template for building more comprehensive subjects.

Ready to extend ULE with your subject? Follow this guide and watch the magic happen! 🚀

Questions? Open an issue or contribute to the ULE repository

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🚀 ULE Extendibility Guide - Adding New Learning Subjects

✨ The Magic: Automatic Discovery

📋 Complete Step-by-Step Guide

Step 1: Create Subject Directory Structure

Step 2: Create the Question Database

Step 3: Create the Engine Module

Step 4: Create the Subject Launcher

Step 5: Make Executable (Optional but Recommended)

Step 6: Test the Magic! 🎉

🎯 Subject Configuration Options

🔧 Advanced Customization

Custom Content Types

Custom Question Types

Progress File Naming

📋 Naming Conventions for Discovery

🎯 Subject Ideas to Inspire You

Programming Languages

Academic Subjects

Professional Skills

🚀 Community Contribution

Perfect First Contribution: Expand Mathematics! 🧮

For New Subjects

For Existing Subjects

💡 Tips for Success

Question Design

Concept Organization

Testing Your Subject

🎉 The Result

🌟 Real-World Example

FilesExpand file tree

EXTENDIBILITY.md

Latest commit

History

EXTENDIBILITY.md

File metadata and controls

🚀 ULE Extendibility Guide - Adding New Learning Subjects

✨ The Magic: Automatic Discovery

📋 Complete Step-by-Step Guide

Step 1: Create Subject Directory Structure

Step 2: Create the Question Database

Step 3: Create the Engine Module

Step 4: Create the Subject Launcher

Step 5: Make Executable (Optional but Recommended)

Step 6: Test the Magic! 🎉

🎯 Subject Configuration Options

🔧 Advanced Customization

Custom Content Types

Custom Question Types

Progress File Naming

📋 Naming Conventions for Discovery

🎯 Subject Ideas to Inspire You

Programming Languages

Academic Subjects

Professional Skills

🚀 Community Contribution

Perfect First Contribution: Expand Mathematics! 🧮

For New Subjects

For Existing Subjects

💡 Tips for Success

Question Design

Concept Organization

Testing Your Subject

🎉 The Result

🌟 Real-World Example