Skip to content

Latest commit

 

History

History
312 lines (226 loc) · 9.46 KB

AGENTS.md

File metadata and controls

312 lines (226 loc) · 9.46 KB

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:

# 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

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

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

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:

# 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

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:

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

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