Co-authored-by: BethanyJep <44121227+BethanyJep@users.noreply.github.com>copilot/fix-241c1305-6ad2-4101-a0fa-ab5293fc44ff
copilot-swe-agent[bot]
5 days ago
parent
5d96fd5a08
commit
77d4d7bc8b
@ -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
|
||||
Loading…
Reference in new issue