Merge pull request #879 from microsoft/copilot/fix-241c1305-6ad2-4101-a0fa-ab5293fc44ff

Add AGENTS.md file to provide AI coding agents with project context

Author: leestott

AGENTS.md

@@ -0,0 +1,331 @@
+# 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:
+
+```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 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