Merge pull request #535 from microsoft/copilot/fix-8092275a-9d27-41b1-af6f-a898eb34ed49
Add AGENTS.md file to provide AI coding agents with comprehensive project context
This commit is contained in:
Lee Stott
GitHub
commit
d28a28132d
|
|
@ -0,0 +1,312 @@
|
|||
# AGENTS.md
|
||||
|
||||
## Project Overview
|
||||
|
||||
AI for Beginners is a comprehensive 12-week, 24-lesson curriculum covering Artificial Intelligence fundamentals. This educational repository includes practical lessons using Jupyter Notebooks, quizzes, and hands-on labs. The curriculum covers:
|
||||
|
||||
- Symbolic AI with Knowledge Representation and Expert Systems
|
||||
- Neural Networks and Deep Learning with TensorFlow and PyTorch
|
||||
- Computer Vision techniques and architectures
|
||||
- Natural Language Processing (NLP) including transformers and BERT
|
||||
- Specialized topics: Genetic Algorithms, Reinforcement Learning, Multi-Agent Systems
|
||||
- AI Ethics and Responsible AI principles
|
||||
|
||||
**Key Technologies:** Python 3, Jupyter Notebooks, TensorFlow, PyTorch, Keras, OpenCV, Vue.js (for quiz app)
|
||||
|
||||
**Architecture:** Educational content repository with Jupyter Notebooks organized by topic areas, supplemented by a Vue.js-based quiz application and extensive multi-language support.
|
||||
|
||||
## Setup Commands
|
||||
|
||||
### Primary Development Environment (Python/Jupyter)
|
||||
|
||||
The curriculum is designed to run with Python and Jupyter Notebooks. The recommended approach is using miniconda:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/microsoft/ai-for-beginners
|
||||
cd ai-for-beginners
|
||||
|
||||
# Create and activate conda environment
|
||||
conda env create --name ai4beg --file environment.yml
|
||||
conda activate ai4beg
|
||||
|
||||
# Start Jupyter Notebook
|
||||
jupyter notebook
|
||||
# OR
|
||||
jupyter lab
|
||||
```
|
||||
|
||||
### Alternative: Using devcontainer
|
||||
|
||||
```bash
|
||||
# Open in VS Code and select "Reopen in Container" when prompted
|
||||
# The devcontainer will automatically set up the environment
|
||||
```
|
||||
|
||||
### Quiz Application Setup
|
||||
|
||||
The quiz app is a separate Vue.js application located in `etc/quiz-app/`:
|
||||
|
||||
```bash
|
||||
cd etc/quiz-app
|
||||
npm install
|
||||
npm run serve # Development server
|
||||
npm run build # Production build
|
||||
npm run lint # Lint and fix files
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Working with Jupyter Notebooks
|
||||
|
||||
1. **Local Development:**
|
||||
- Activate conda environment: `conda activate ai4beg`
|
||||
- Start Jupyter: `jupyter notebook` or `jupyter lab`
|
||||
- Navigate to lesson folders and open `.ipynb` files
|
||||
- Run cells interactively to follow lessons
|
||||
|
||||
2. **VS Code with Python Extension:**
|
||||
- Open repository in VS Code
|
||||
- Install Python extension
|
||||
- VS Code automatically detects and uses the conda environment
|
||||
- Open `.ipynb` files directly in VS Code
|
||||
|
||||
3. **Cloud Development:**
|
||||
- **GitHub Codespaces:** Click "Code" → "Codespaces" → "Create codespace on main"
|
||||
- **Binder:** Use the Binder badge on README to launch in browser
|
||||
- Note: Binder has limited resources and some web access restrictions
|
||||
|
||||
### GPU Support for Advanced Lessons
|
||||
|
||||
Later lessons benefit significantly from GPU acceleration:
|
||||
|
||||
- **Azure Data Science VM:** Use NC-series VMs with GPU support
|
||||
- **Azure Machine Learning:** Use notebook features with GPU compute
|
||||
- **Google Colab:** Upload notebooks individually (has free GPU support)
|
||||
|
||||
### Quiz App Development
|
||||
|
||||
```bash
|
||||
cd etc/quiz-app
|
||||
npm run serve # Hot-reload development server at http://localhost:8080
|
||||
```
|
||||
|
||||
## Testing Instructions
|
||||
|
||||
This is an educational repository focused on learning content rather than software testing. There is no traditional test suite.
|
||||
|
||||
### Validation Approaches:
|
||||
|
||||
1. **Jupyter Notebooks:** Execute cells sequentially to verify code examples work
|
||||
2. **Quiz App Testing:** Manual testing via development server
|
||||
3. **Translation Validation:** Check translated content in `translations/` folder
|
||||
4. **Quiz App Linting:** `npm run lint` in `etc/quiz-app/`
|
||||
|
||||
### Running Code Examples:
|
||||
|
||||
```bash
|
||||
# Activate environment first
|
||||
conda activate ai4beg
|
||||
|
||||
# Run Python scripts directly
|
||||
python lessons/4-ComputerVision/07-ConvNets/pytorchcv.py
|
||||
|
||||
# Or execute notebooks
|
||||
jupyter notebook lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
### Python Code Style
|
||||
|
||||
- Standard Python conventions for educational code
|
||||
- Clear, readable code prioritizing learning over optimization
|
||||
- Comments explaining key concepts
|
||||
- Jupyter Notebook-friendly: cells should be self-contained where possible
|
||||
- No strict linting requirements for lesson content
|
||||
|
||||
### JavaScript/Vue.js (Quiz App)
|
||||
|
||||
- ESLint configuration in `etc/quiz-app/package.json`
|
||||
- Run `npm run lint` to check and auto-fix issues
|
||||
- Vue 2.x conventions
|
||||
- Component-based architecture
|
||||
|
||||
### File Organization
|
||||
|
||||
```
|
||||
lessons/
|
||||
├── 0-course-setup/ # Setup instructions
|
||||
├── 1-Intro/ # Introduction to AI
|
||||
├── 2-Symbolic/ # Symbolic AI
|
||||
├── 3-NeuralNetworks/ # Neural Networks basics
|
||||
├── 4-ComputerVision/ # Computer Vision
|
||||
├── 5-NLP/ # Natural Language Processing
|
||||
├── 6-Other/ # Other AI techniques
|
||||
├── 7-Ethics/ # AI Ethics
|
||||
└── X-Extras/ # Additional content
|
||||
|
||||
etc/
|
||||
├── quiz-app/ # Vue.js quiz application
|
||||
└── quiz-src/ # Quiz source files
|
||||
|
||||
translations/ # Multi-language translations
|
||||
```
|
||||
|
||||
## Build and Deployment
|
||||
|
||||
### Jupyter Content
|
||||
|
||||
No build process required - Jupyter Notebooks are executed directly.
|
||||
|
||||
### Quiz Application
|
||||
|
||||
```bash
|
||||
cd etc/quiz-app
|
||||
|
||||
# Development
|
||||
npm run serve
|
||||
|
||||
# Production build
|
||||
npm run build # Outputs to etc/quiz-app/dist/
|
||||
|
||||
# Deploy to Azure Static Web Apps
|
||||
# Azure automatically creates GitHub Actions workflow
|
||||
# See etc/quiz-app/README.md for detailed deployment instructions
|
||||
```
|
||||
|
||||
### Documentation Site
|
||||
|
||||
The repository uses Docsify for documentation:
|
||||
- `index.html` serves as entry point
|
||||
- No build required - served directly via GitHub Pages
|
||||
- Access at: https://microsoft.github.io/AI-For-Beginners/
|
||||
|
||||
## Contributing Guidelines
|
||||
|
||||
### Pull Request Process
|
||||
|
||||
1. **Title Format:** Clear, descriptive titles describing the change
|
||||
2. **CLA Requirement:** Microsoft CLA must be signed (automated check)
|
||||
3. **Content Guidelines:**
|
||||
- Maintain educational focus and beginner-friendly approach
|
||||
- Test all code examples in notebooks
|
||||
- Ensure notebooks run end-to-end
|
||||
- Update translations if modifying English content
|
||||
4. **Quiz App Changes:** Run `npm run lint` before committing
|
||||
|
||||
### Translation Contributions
|
||||
|
||||
- Translations are automated via GitHub Actions using co-op-translator
|
||||
- Manual translations go in `translations/<language-code>/`
|
||||
- Quiz translations in `etc/quiz-app/src/assets/translations/`
|
||||
- Supported languages: 40+ languages (see README for full list)
|
||||
|
||||
### Active Contribution Areas
|
||||
|
||||
See `etc/CONTRIBUTING.md` for current needs:
|
||||
- Deep Reinforcement Learning sections
|
||||
- Object Detection improvements
|
||||
- Named Entity Recognition examples
|
||||
- Custom embedding training samples
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Required Dependencies
|
||||
|
||||
```bash
|
||||
# Core Python packages (from requirements.txt)
|
||||
tensorflow==2.17.0
|
||||
torch (via conda)
|
||||
torchvision (via conda)
|
||||
keras==3.5.0
|
||||
opencv (via conda)
|
||||
scikit-learn
|
||||
numpy==1.26
|
||||
pandas==2.2.2
|
||||
matplotlib==3.9
|
||||
jupyter
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
No special environment variables required for basic usage.
|
||||
|
||||
For Azure deployments (quiz app):
|
||||
- `AZURE_STATIC_WEB_APPS_API_TOKEN` (set automatically by Azure)
|
||||
|
||||
## Debugging and Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue:** Conda environment creation fails
|
||||
- **Solution:** Update conda first: `conda update conda -y`
|
||||
- Ensure sufficient disk space (50GB recommended)
|
||||
|
||||
**Issue:** Jupyter kernel not found
|
||||
- **Solution:**
|
||||
```bash
|
||||
conda activate ai4beg
|
||||
python -m ipykernel install --user --name ai4beg
|
||||
```
|
||||
|
||||
**Issue:** GPU not detected in notebooks
|
||||
- **Solution:**
|
||||
- Verify CUDA installation: `nvidia-smi`
|
||||
- Check PyTorch GPU: `python -c "import torch; print(torch.cuda.is_available())"`
|
||||
- Check TensorFlow GPU: `python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"`
|
||||
|
||||
**Issue:** Quiz app won't start
|
||||
- **Solution:**
|
||||
```bash
|
||||
cd etc/quiz-app
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
npm run serve
|
||||
```
|
||||
|
||||
**Issue:** Binder times out or blocks downloads
|
||||
- **Solution:** Use GitHub Codespaces or local setup for better resource access
|
||||
|
||||
### Memory Issues
|
||||
|
||||
Some lessons require significant RAM (8GB+ recommended):
|
||||
- Use cloud VMs for resource-intensive lessons
|
||||
- Close other applications when training models
|
||||
- Reduce batch sizes in notebooks if running out of memory
|
||||
|
||||
## Additional Notes
|
||||
|
||||
### For Course Instructors
|
||||
|
||||
- See `lessons/0-course-setup/for-teachers.md` for teaching guidance
|
||||
- Lessons are self-contained and can be taught in sequence or selected individually
|
||||
- Estimated time: 12 weeks at 2 lessons per week
|
||||
|
||||
### Cloud Resources
|
||||
|
||||
- **Azure for Students:** Free credits available for students
|
||||
- **Microsoft Learn:** Supplementary learning paths linked throughout
|
||||
- **Binder:** Free but limited resources and some network restrictions
|
||||
|
||||
### Code Execution Options
|
||||
|
||||
1. **Local (Recommended):** Full control, best performance, GPU support
|
||||
2. **GitHub Codespaces:** Cloud-based VS Code, good for quick access
|
||||
3. **Binder:** Browser-based Jupyter, free but limited
|
||||
4. **Azure ML Notebooks:** Enterprise option with GPU support
|
||||
5. **Google Colab:** Upload notebooks individually, free GPU tier available
|
||||
|
||||
### Working with Notebooks
|
||||
|
||||
- Notebooks are designed to be run cell-by-cell for learning
|
||||
- Many notebooks download datasets on first run (may take time)
|
||||
- Some models require GPU for reasonable training times
|
||||
- Pre-trained models are used where possible to reduce compute requirements
|
||||
|
||||
### Performance Considerations
|
||||
|
||||
- Later computer vision lessons (CNNs, GANs) benefit from GPU
|
||||
- NLP transformer lessons may require significant RAM
|
||||
- Training from scratch is educational but time-consuming
|
||||
- Transfer learning examples minimize training time
|
||||
Loading…
Reference in New Issue