Initial commit of ULE v1.0

Author: RyanRustill

.gitignore

@@ -0,0 +1,261 @@
+# ULE - Universal Learning Engine .gitignore
+# Protects private development documentation and user data
+
+# ================================
+# CRITICAL - NEVER COMMIT THESE
+# ================================
+
+# Private Documentation (NEVER commit these)
+docs/private/
+private_notes.md
+development_log.md
+*.private.md
+*_private.md
+planning/
+roadmap.private.*
+
+# User Data & Progress (NEVER commit these)
+*_progress.json
+user_progress/
+sessions/
+student_data/
+learning_analytics/
+*.user.json
+
+# ================================
+# PYTHON & DEVELOPMENT
+# ================================
+
+# Python Runtime
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+
+# Virtual Environments
+env/
+venv/
+.env
+.venv
+ENV/
+env.bak/
+venv.bak/
+.virtualenv
+.pipenv/
+
+# Environment Variables
+.env
+.env.local
+.env.development
+.env.test
+.env.production
+*.env
+
+# ================================
+# IDEs & EDITORS
+# ================================
+
+# VSCode
+.vscode/
+*.code-workspace
+
+# PyCharm / IntelliJ
+.idea/
+*.iws
+*.iml
+*.ipr
+
+# Vim / Emacs
+*.swp
+*.swo
+*~
+.vim/
+.emacs.d/
+
+# Sublime Text
+*.sublime-workspace
+*.sublime-project
+
+# Atom
+.atom/
+
+# ================================
+# OPERATING SYSTEMS
+# ================================
+
+# macOS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+.AppleDouble
+.LSOverride
+Icon?
+
+# Windows
+ehthumbs.db
+Thumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# Linux
+*~
+.directory
+.Trash-*
+
+# ================================
+# DATA & DATABASES
+# ================================
+
+# Database Files
+*.db
+*.sqlite
+*.sqlite3
+*.db-journal
+
+# Data Files (potentially sensitive)
+*.csv.backup
+*.json.backup
+*.json.bak
+backup_*.json
+*.backup
+
+# Pickle Files (can contain code)
+*.pickle
+*.pkl
+
+# ================================
+# JUPYTER & NOTEBOOKS
+# ================================
+
+# Jupyter Notebook
+.ipynb_checkpoints/
+*.ipynb
+*-checkpoint.ipynb
+.jupyter/
+
+# IPython
+profile_default/
+ipython_config.py
+
+# ================================
+# TEMPORARY & CACHE FILES
+# ================================
+
+# Temporary Files
+*.tmp
+*.temp
+temp/
+tmp/
+.tmp/
+cache/
+.cache/
+
+# Log Files
+*.log
+*.log.*
+debug.txt
+error.log
+output.log
+nohup.out
+
+# ================================
+# TESTING & COVERAGE
+# ================================
+
+# Testing Frameworks
+.pytest_cache/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+
+# Coverage Reports
+htmlcov/
+coverage/
+.nyc_output/
+
+# ================================
+# PACKAGING & DISTRIBUTION
+# ================================
+
+# Python Packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# ================================
+# DOCUMENTATION & MEDIA
+# ================================
+
+# Generated Documentation
+docs/_build/
+docs/build/
+site/
+
+# Media Files (if large)
+*.mp4
+*.avi
+*.mov
+*.wmv
+*.flv
+*.webm
+
+# ================================
+# LEARNING ENGINE SPECIFIC
+# ================================
+
+# Question Database Backups
+*_questions_backup.json
+questions_*.bak
+*_export.json
+
+# Performance & Analytics
+performance_*.json
+analytics_*.json
+stats_*.json
+metrics_*.json
+
+# AI Model Files (if added later)
+*.model
+*.weights
+*.h5
+*.ckpt
+*.pb
+
+# Configuration Overrides
+config.local.*
+settings.local.*
+*.local.json
+
+# Debug & Development
+debug_*.py
+test_*.tmp
+scratch_*.py 

ABOUT.md

@@ -0,0 +1,68 @@
+# 🌱 About the Universal Learning Engine (ULE)
+
+The **Universal Learning Engine (ULE)** is an adaptive, open-source terminal-based platform designed to help learners build deep understanding through code-based reasoning challenges. It provides a modular system for creating and delivering multiple-choice question sets across a wide range of subjects — from programming to logic to mathematics and beyond.
+
+---
+
+## 🎓 Origins
+
+ULE began in 2025 as a personal learning project by **Ryan Rustill**, exploring how to teach Python fundamentals through structured code reading challenges. What started as a small snippet grew — with the help of community feedback — into a much larger idea:
+
+> *"What if we built a lightweight, universal engine for teaching anything through adaptive questioning?"*
+
+That idea became the foundation for ULE:  
+- Subject-agnostic  
+- JSON-driven  
+- Progressively adaptive  
+- Beautifully simple
+
+While the early engine was built specifically for Python, the core architecture was soon redesigned to support any subject area with minimal effort from contributors.
+
+---
+
+## 🚀 Mission
+
+The goal is simple:  
+**Make self-paced learning intelligent, structured, and welcoming to everyone.**
+
+I believe that:
+- Learning should **adapt** to the learner — not the other way around  
+- Educational tools should be **transparent, explainable, and hackable**  
+- Reasoning is a muscle, and this engine is your gym
+
+---
+
+## 🛠️ What's Inside
+
+ULE features:
+- A fully modular adaptive engine
+- Support for subject-specific modules (Python, Math, etc.)
+- Auto-discovery of available subject sets
+- Terminal-based UI with color-coded feedback
+- Session-based learning, difficulty tracking, and progress adaptation
+
+---
+
+## 📬 Join the Journey
+
+ULE is open-source and welcomes contributors of all backgrounds.
+
+If you:
+- Love learning
+- Want to build your own subject modules
+- Care about accessible, open education  
+→ [check out our CONTRIBUTING.md](./CONTRIBUTING.md) to get started.
+
+Whether you're an educator, a developer, a learner, or all three — you're welcome here.
+
+---
+
+## 🌿 Legacy
+
+The **Universal Learning Engine** is the foundational core of a broader vision called **ReasonRoot**, a minimalist mobile platform for calm, focused, emotionally positive learning.
+
+ULE will always remain free and open for the world to build on.
+
+It is a standalone, open-source project. Some features or concepts may inspire or overlap with ReasonRoot, but community contributions to ULE remain MIT-licensed and fully open.
+
+**Happy learning.**