# AGENTS.md

## Project Overview

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

Key components:
- **Educational Content**: 26 lessons covering topics like ML introduction, regression, classification, clustering, NLP, time series, and reinforcement learning
- **Quiz Application**: A Vue.js-based quiz app with pre- and post-lesson assessments
- **Multi-language Support**: Automated translations into 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:

```bash
# 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 located in `solution/R/` folders as `.rmd` or `.ipynb` files:

```bash
# 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:

```bash
cd quiz-app
npm install
```

### For Documentation Site

To run the documentation locally:

```bash
# 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:
   ```bash
   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

```bash
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

```bash
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:

```bash
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](CODE_OF_CONDUCT.md)
- **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

```bash
# 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](https://learn.microsoft.com/en-us/collections/qrqzamz1nn2wx3?WT.mc_id=academic-77952-bethanycheum)
- **Quiz App**: [Online quizzes](https://ff-quizzes.netlify.app/en/ml/)
- **Discussion Board**: [GitHub Discussions](https://github.com/microsoft/ML-For-Beginners/discussions)
- **Video Walkthroughs**: [YouTube Playlist](https://aka.ms/ml-beginners-videos)

## 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

---

**Disclaimer**:  
This document has been translated using the AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please note that automated translations may contain errors or inaccuracies. The original document in its native language should be regarded as the authoritative source. For critical information, professional human translation is recommended. We are not responsible for any misunderstandings or misinterpretations resulting from the use of this translation.