ML-For-Beginners/AGENTS.md

AGENTS.md

Project Overview

This is Machine Learning for Beginners, a comprehensive 12-week, 26-lesson curriculum covering classic machine learning concepts using Python (primarily with Scikit-learn) and R. The repository is designed as a self-paced learning resource with hands-on projects, quizzes, and assignments. Each lesson explores ML concepts through real-world data from various cultures and regions worldwide.

Key components:

• Educational Content: 26 lessons covering introduction to ML, regression, classification, clustering, NLP, time series, and reinforcement learning
• Quiz Application: Vue.js-based quiz app with pre- and post-lesson assessments
• Multi-language Support: Automated translations to 40+ languages via GitHub Actions
• Dual Language Support: Lessons available in both Python (Jupyter notebooks) and R (R Markdown files)
• Project-Based Learning: Each topic includes practical projects and assignments

Repository Structure

ML-For-Beginners/
├── 1-Introduction/         # ML basics, history, fairness, techniques
├── 2-Regression/          # Regression models with Python/R
├── 3-Web-App/            # Flask web app for ML model deployment
├── 4-Classification/      # Classification algorithms
├── 5-Clustering/         # Clustering techniques
├── 6-NLP/               # Natural Language Processing
├── 7-TimeSeries/        # Time series forecasting
├── 8-Reinforcement/     # Reinforcement learning
├── 9-Real-World/        # Real-world ML applications
├── quiz-app/           # Vue.js quiz application
├── translations/       # Auto-generated translations
└── sketchnotes/       # Visual learning aids

Each lesson folder typically contains:

• README.md - Main lesson content
• notebook.ipynb - Python Jupyter notebook
• solution/ - Solution code (Python and R versions)
• assignment.md - Practice exercises
• images/ - Visual resources

Setup Commands

For Python Lessons

Most lessons use Jupyter notebooks. Install required dependencies:

# Install Python 3.8+ if not already installed
python --version

# Install Jupyter
pip install jupyter

# Install common ML libraries
pip install scikit-learn pandas numpy matplotlib seaborn

# For specific lessons, check lesson-specific requirements
# Example: Web App lesson
pip install flask

For R Lessons

R lessons are in solution/R/ folders as .rmd or .ipynb files:

# Install R and required packages
# In R console:
install.packages(c("tidyverse", "tidymodels", "caret"))

For Quiz Application

The quiz app is a Vue.js application located in the quiz-app/ directory:

cd quiz-app
npm install

For Documentation Site

To run the documentation locally:

# Install Docsify
npm install -g docsify-cli

# Serve from repository root
docsify serve

# Access at http://localhost:3000

Development Workflow

Working with Lesson Notebooks

1. Navigate to the lesson directory (e.g., 2-Regression/1-Tools/)
2. Open the Jupyter notebook:

   jupyter notebook notebook.ipynb
   

3. Work through the lesson content and exercises
4. Check solutions in the solution/ folder if needed

Python Development

• Lessons use standard Python data science libraries
• Jupyter notebooks for interactive learning
• Solution code available in each lesson's solution/ folder

R Development

• R lessons are in .rmd format (R Markdown)
• Solutions located in solution/R/ subdirectories
• Use RStudio or Jupyter with R kernel to run R notebooks

Quiz Application Development

cd quiz-app

# Start development server
npm run serve
# Access at http://localhost:8080

# Build for production
npm run build

# Lint and fix files
npm run lint

Testing Instructions

Quiz Application Testing

cd quiz-app

# Lint code
npm run lint

# Build to verify no errors
npm run build

Note: This is primarily an educational curriculum repository. There are no automated tests for lesson content. Validation is done through:

• Completing lesson exercises
• Running notebook cells successfully
• Checking output against expected results in solutions

Code Style Guidelines

Python Code

• Follow PEP 8 style guidelines
• Use clear, descriptive variable names
• Include comments for complex operations
• Jupyter notebooks should have markdown cells explaining concepts

JavaScript/Vue.js (Quiz App)

• Follows Vue.js style guide
• ESLint configuration in quiz-app/package.json
• Run npm run lint to check and auto-fix issues

Documentation

• Markdown files should be clear and well-structured
• Include code examples in fenced code blocks
• Use relative links for internal references
• Follow existing formatting conventions

Build and Deployment

Quiz Application Deployment

The quiz app can be deployed to Azure Static Web Apps:

1. Prerequisites:

   • Azure account
   • GitHub repository (already forked)

2. Deploy to Azure:

   • Create Azure Static Web App resource
   • Connect to GitHub repository
   • Set app location: /quiz-app
   • Set output location: dist
   • Azure automatically creates GitHub Actions workflow

3. GitHub Actions Workflow:

   • Workflow file created at .github/workflows/azure-static-web-apps-*.yml
   • Automatically builds and deploys on push to main branch

Documentation PDF

Generate PDF from documentation:

npm install
npm run convert

Translation Workflow

Important: Translations are automated via GitHub Actions using Co-op Translator.

• Translations are auto-generated when changes are pushed to main branch
• DO NOT manually translate content - the system handles this
• Workflow defined in .github/workflows/co-op-translator.yml
• Uses Azure AI/OpenAI services for translation
• Supports 40+ languages

Contributing Guidelines

For Content Contributors

1. Fork the repository and create a feature branch
2. Make changes to lesson content if adding/updating lessons
3. Do not modify translated files - they are auto-generated
4. Test your code - ensure all notebook cells run successfully
5. Verify links and images work correctly
6. Submit a pull request with clear description

Pull Request Guidelines

• Title format: [Section] Brief description of changes
  • Example: [Regression] Fix typo in lesson 5
  • Example: [Quiz-App] Update dependencies
• Before submitting:
  • Ensure all notebook cells execute without errors
  • Run npm run lint if modifying quiz-app
  • Verify markdown formatting
  • Test any new code examples
• PR must include:
  • Description of changes
  • Reason for changes
  • Screenshots if UI changes
• Code of Conduct: Follow the Microsoft Open Source Code of Conduct
• CLA: You will need to sign the Contributor License Agreement

Lesson Structure

Each lesson follows a consistent pattern:

1. Pre-lecture quiz - Test baseline knowledge
2. Lesson content - Written instructions and explanations
3. Code demonstrations - Hands-on examples in notebooks
4. Knowledge checks - Verify understanding throughout
5. Challenge - Apply concepts independently
6. Assignment - Extended practice
7. Post-lecture quiz - Assess learning outcomes

Common Commands Reference

# Python/Jupyter
jupyter notebook                    # Start Jupyter server
jupyter notebook notebook.ipynb     # Open specific notebook
pip install -r requirements.txt     # Install dependencies (where available)

# Quiz App
cd quiz-app
npm install                        # Install dependencies
npm run serve                      # Development server
npm run build                      # Production build
npm run lint                       # Lint and fix

# Documentation
docsify serve                      # Serve documentation locally
npm run convert                    # Generate PDF

# Git workflow
git checkout -b feature/my-change  # Create feature branch
git add .                         # Stage changes
git commit -m "Description"       # Commit changes
git push origin feature/my-change # Push to remote

Additional Resources

• Microsoft Learn Collection: ML for Beginners modules
• Quiz App: Online quizzes
• Discussion Board: GitHub Discussions
• Video Walkthroughs: YouTube Playlist

Key Technologies

• Python: Primary language for ML lessons (Scikit-learn, Pandas, NumPy, Matplotlib)
• R: Alternative implementation using tidyverse, tidymodels, caret
• Jupyter: Interactive notebooks for Python lessons
• R Markdown: Documents for R lessons
• Vue.js 3: Quiz application framework
• Flask: Web application framework for ML model deployment
• Docsify: Documentation site generator
• GitHub Actions: CI/CD and automated translations

Security Considerations

• No secrets in code: Never commit API keys or credentials
• Dependencies: Keep npm and pip packages updated
• User input: Flask web app examples include basic input validation
• Sensitive data: Example datasets are public and non-sensitive

Troubleshooting

Jupyter Notebooks

• Kernel issues: Restart kernel if cells hang: Kernel → Restart
• Import errors: Ensure all required packages are installed with pip
• Path issues: Run notebooks from their containing directory

Quiz Application

• npm install fails: Clear npm cache: npm cache clean --force
• Port conflicts: Change port with: npm run serve -- --port 8081
• Build errors: Delete node_modules and reinstall: rm -rf node_modules && npm install

R Lessons

• Package not found: Install with: install.packages("package-name")
• RMarkdown rendering: Ensure rmarkdown package is installed
• Kernel issues: May need to install IRkernel for Jupyter

Project-Specific Notes

• This is primarily a learning curriculum, not production code
• Focus is on understanding ML concepts through hands-on practice
• Code examples prioritize clarity over optimization
• Most lessons are self-contained and can be completed independently
• Solutions provided but learners should attempt exercises first
• Repository uses Docsify for web documentation without build step
• Sketchnotes provide visual summaries of concepts
• Multi-language support makes content globally accessible