Skip to content

AGENTS.md

Latest commit

 

History

History
656 lines (485 loc) · 19.3 KB

AGENTS.md

File metadata and controls

656 lines (485 loc) · 19.3 KB

AGENTS.md

Developer Guide for Contributing to EdgeAI for Beginners

This document provides comprehensive information for developers, AI agents, and contributors working with this repository. It covers setup, development workflows, testing, and best practices.

Last Updated: October 2025 | Document Version: 2.0

Table of Contents

Project Overview

EdgeAI for Beginners is a comprehensive educational repository teaching Edge AI development with Small Language Models (SLMs). The course covers EdgeAI fundamentals, model deployment, optimization techniques, and production-ready implementations using Microsoft Foundry Local and various AI frameworks.

Key Technologies:

  • Python 3.8+ (primary language for AI/ML samples)
  • .NET C# (AI/ML Samples)
  • JavaScript/Node.js with Electron (for desktop applications)
  • Microsoft Foundry Local SDK
  • Microsoft Windows ML
  • VSCode AI Toolkit
  • OpenAI SDK
  • AI Frameworks: LangChain, Semantic Kernel, Chainlit
  • Model Optimization: Llama.cpp, Microsoft Olive, OpenVINO, Apple MLX

Repository Type: Educational content repository with 8 modules and 10 comprehensive sample applications

Architecture: Multi-module learning path with practical samples demonstrating edge AI deployment patterns

Repository Structure

edgeai-for-beginners/
├── introduction.md          # Course introduction and overview
├── Module01-07/            # Core educational modules (Markdown)
├── Module08/               # Foundry Local toolkit with 10 samples
│   ├── samples/01-06/     # Foundation samples (Python)
│   ├── samples/07/        # API client (Python)
│   ├── samples/08/        # Windows 11 chat app (Electron)
│   └── samples/09-10/     # Advanced multi-agent systems (Python)
├── translations/          # Multi-language translations (50+ languages)
├── translated_images/     # Localized images
└── imgs/                  # Course images and assets

Prerequisites

Required Tools

  • Python 3.8+ - For AI/ML samples and notebooks
  • Node.js 16+ - For Electron sample application
  • Git - For version control
  • Microsoft Foundry Local - For running AI models locally

Recommended Tools

  • Visual Studio Code - With Python, Jupyter, and Pylance extensions
  • Windows Terminal - For better command-line experience (Windows users)
  • Docker - For containerized development (optional)

System Requirements

  • RAM: 8GB minimum, 16GB+ recommended for multi-model scenarios
  • Storage: 10GB+ free space for models and dependencies
  • OS: Windows 10/11, macOS 11+, or Linux (Ubuntu 20.04+)
  • Hardware: CPU with AVX2 support; GPU (CUDA, Qualcomm NPU) optional but recommended

Knowledge Prerequisites

  • Basic understanding of Python programming
  • Familiarity with command-line interfaces
  • Understanding of AI/ML concepts (for sample development)
  • Git workflows and pull request processes

Setup Commands

Repository Setup

# Clone the repository
git clone https://github.com/microsoft/edgeai-for-beginners.git
cd edgeai-for-beginners

# No build step required - this is primarily an educational content repository

Python Sample Setup (Module08 and Python samples)

# Create and activate virtual environment
python -m venv .venv
# On Windows
.venv\Scripts\activate
# On macOS/Linux
source .venv/bin/activate

# Install Foundry Local SDK and dependencies
pip install foundry-local-sdk openai

# Install additional dependencies for Module08 samples
cd Module08
pip install -r requirements.txt

Node.js Sample Setup (Sample 08 - Windows Chat App)

cd Module08/samples/08
npm install

# Start in development mode
npm run dev

# Build for production
npm run build

# Create installer
npm run dist

Foundry Local Setup

Foundry Local is required to run the samples. Download and install from the official repository:

Installation:

  • Windows: winget install Microsoft.FoundryLocal
  • macOS: brew tap microsoft/foundrylocal && brew install foundrylocal
  • Manual: Download from releases page

Quick Start:

# Run your first model (auto-downloads if needed)
foundry model run phi-3.5-mini

# List available models
foundry model ls

# Check service status
foundry service status

Note: Foundry Local automatically selects the best model variant for your hardware (CUDA GPU, Qualcomm NPU, or CPU).

Development Workflow

Content Development

This repository contains primarily Markdown educational content. When making changes:

  1. Edit .md files in the appropriate module directories
  2. Follow existing formatting patterns
  3. Ensure code examples are accurate and tested
  4. Update corresponding translated content if necessary (or let automation handle it)

Sample Application Development

For Python samples (samples 01-07, 09-10):

cd Module08
python samples/01/chat_quickstart.py "Test message"

For Electron sample (sample 08):

cd Module08/samples/08
npm run dev  # Development with hot reload

Testing Sample Applications

Python samples don't have automated tests but can be validated by running them:

# Test basic chat functionality
python samples/01/chat_quickstart.py "Hello"

# Test with specific model
set MODEL=phi-4-mini
python samples/02/openai_sdk_client.py

Electron sample has test infrastructure:

cd Module08/samples/08
npm test           # Run unit tests
npm run test:e2e   # Run end-to-end tests
npm run lint       # Check code style

Testing Instructions

Content Validation

The repository uses automated translation workflows. No manual testing required for translations.

Manual validation for content changes:

  1. Review Markdown rendering by previewing .md files
  2. Verify all links point to valid targets
  3. Test any code snippets included in documentation
  4. Check that images load correctly

Sample Application Testing

Module08/samples/08 (Electron app) has comprehensive testing:

cd Module08/samples/08

# Run all tests
npm test

# Run unit tests only
npm test -- --testPathPattern=unit

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

# Check test coverage
npm test -- --coverage

Python samples should be manually tested:

# Each sample can be run directly
python samples/01/chat_quickstart.py "Test prompt"
python samples/04/chainlit_rag.py
python samples/09/multi_agent_system.py

Code Style Guidelines

Markdown Content

  • Use consistent heading hierarchy (# for title, ## for main sections, ### for subsections)
  • Include code blocks with language specifiers: python, bash, ```javascript
  • Follow existing formatting for tables, lists, and emphasis
  • Keep lines readable (aim for ~80-100 characters, but not strict)
  • Use relative links for internal references

Python Code Style

  • Follow PEP 8 conventions
  • Use type hints where appropriate
  • Include docstrings for functions and classes
  • Use meaningful variable names
  • Keep functions focused and concise

JavaScript/Node.js Code Style

# Electron sample follows ESLint configuration
cd Module08/samples/08
npm run lint        # Check for style issues
npm run lint:fix    # Auto-fix style issues
npm run format      # Format with Prettier

Key conventions:

  • ESLint configuration provided in sample 08
  • Prettier for code formatting
  • Use modern ES6+ syntax
  • Follow existing patterns in the codebase

Pull Request Guidelines

Contribution Workflow

  1. Fork the repository and create a new branch from main
  2. Make your changes following the code style guidelines
  3. Test thoroughly using the testing instructions above
  4. Commit with clear messages following conventional commits format
  5. Push to your fork and create a pull request
  6. Respond to feedback from maintainers during review

Branch Naming Convention

  • feature/<module>-<description> - For new features or content
  • fix/<module>-<description> - For bug fixes
  • docs/<description> - For documentation improvements
  • refactor/<description> - For code refactoring

Commit Message Format

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Examples:

feat(Module08): add intent-based routing notebook
docs(AGENTS): update Foundry Local setup instructions
fix(samples/08): resolve Electron build issue

Title Format

[ModuleXX] Brief description of change

or

[Module08/samples/XX] Description for sample changes

Code of Conduct

All contributors must follow the Microsoft Open Source Code of Conduct. Please review CODE_OF_CONDUCT.md before contributing.

Before Submitting

For content changes:

  • Preview all modified Markdown files
  • Verify links and images work
  • Check for typos and grammatical errors

For sample code changes (Module08/samples/08):

npm run lint
npm test

For Python sample changes:

  • Test the sample runs successfully
  • Verify error handling works
  • Check compatibility with Foundry Local

Review Process

  • Educational content changes are reviewed for accuracy and clarity
  • Code samples are tested for functionality
  • Translation updates are handled automatically by GitHub Actions

Translation System

IMPORTANT: This repository uses automated translation via GitHub Actions.

  • Translations are in /translations/ directory (50+ languages)
  • Automated via co-op-translator.yml workflow
  • DO NOT manually edit translation files - they will be overwritten
  • Edit only English source files in root and module directories
  • Translations are automatically generated on push to main branch

Foundry Local Integration

Most Module08 samples require Microsoft Foundry Local to be running.

Installation & Setup

Install Foundry Local:

# Windows
winget install Microsoft.FoundryLocal

# macOS
brew tap microsoft/foundrylocal
brew install foundrylocal

Install Python SDK:

pip install foundry-local-sdk openai

Starting Foundry Local

# Start service and run a model (auto-downloads if needed)
foundry model run phi-3.5-mini

# Or use model aliases for automatic hardware optimization
foundry model run phi-4-mini
foundry model run qwen2.5-0.5b
foundry model run qwen2.5-coder-0.5b

# Check service status
foundry service status

# List available models
foundry model ls

SDK Usage (Python)

from foundry_local import FoundryLocalManager
import openai

# Use model alias for automatic hardware optimization
alias = "phi-3.5-mini"

# Create manager (auto-starts service and loads model)
manager = FoundryLocalManager(alias)

# Configure OpenAI client for local Foundry service
client = openai.OpenAI(
    base_url=manager.endpoint,
    api_key=manager.api_key
)

# Use the model
response = client.chat.completions.create(
    model=manager.get_model_info(alias).id,
    messages=[{"role": "user", "content": "Hello!"}]
)

Verifying Foundry Local

# Service status and endpoint
foundry service status

# List loaded models (REST API)
curl http://localhost:<port>/v1/models

# Note: Port is displayed when running 'foundry service status'

Environment Variables for Samples

Most samples use these environment variables:

# Foundry Local configuration
# Note: The SDK (FoundryLocalManager) automatically detects endpoint
set MODEL=phi-3.5-mini  # or phi-4-mini, qwen2.5-0.5b, qwen2.5-coder-0.5b
set API_KEY=            # Not required for local usage

# Manual endpoint (if not using SDK)
# Port is shown via 'foundry service status'
set BASE_URL=http://localhost:<port>

# For Azure OpenAI fallback (optional)
set AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
set AZURE_OPENAI_API_KEY=your-api-key
set AZURE_OPENAI_API_VERSION=2024-08-01-preview

Note: When using FoundryLocalManager, the SDK automatically handles service discovery and model loading. Model aliases (like phi-3.5-mini) ensure the best variant is selected for your hardware.

Build and Deployment

Content Deployment

This repository is primarily documentation - no build process required for content.

Sample Application Building

Electron Application (Module08/samples/08):

cd Module08/samples/08

# Development build
npm run dev

# Production build
npm run build

# Create Windows installer
npm run dist

# Create portable executable
npm run pack

Python Samples: No build process - samples are run directly with Python interpreter.

Common Issues and Troubleshooting

Tip: Check GitHub Issues for known problems and solutions.

Critical Issues (Blocking)

Foundry Local Not Running

Issue: Samples fail with connection errors

Solution:

# Check if service is running
foundry service status

# Start service with a model
foundry model run phi-3.5-mini

# Or explicitly start service
foundry service start

# List loaded models
foundry model ls

# Verify via REST API (port shown in 'foundry service status')
curl http://localhost:<port>/v1/models

Common Issues (Moderate)

Python Virtual Environment Issues

Issue: Module import errors

Solution:

# Ensure virtual environment is activated
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

Electron Build Issues

Issue: npm install or build failures

Solution:

cd Module08/samples/08
# Clean install
npm run clean
rm -rf node_modules package-lock.json
npm install

Workflow Issues (Minor)

Translation Workflow Conflicts

Issue: Translation PR conflicts with your changes

Solution:

  • Only edit English source files
  • Let the automated translation workflow handle translations
  • If conflicts occur, merge main into your branch after translations are merged

Model Download Failures

Issue: Foundry Local fails to download models

Solution:

# Check internet connectivity
# Clear model cache and retry
foundry model remove <model-alias>
foundry model run <model-alias>

# Check available disk space (models can be 2-16GB)
# Verify firewall settings allow downloads

Additional Resources

Learning Paths

  • Beginner Path: Modules 01-02 (7-9 hours)
  • Intermediate Path: Modules 03-04 (9-11 hours)
  • Advanced Path: Modules 05-07 (12-15 hours)
  • Expert Path: Module 08 (8-10 hours)

Key Module Content

  • Module01: EdgeAI fundamentals and real-world case studies
  • Module02: Small Language Model (SLM) families and architectures
  • Module03: Local and cloud deployment strategies
  • Module04: Model optimization with multiple frameworks
  • Module05: SLMOps - production operations
  • Module06: AI agents and function calling
  • Module07: Platform-specific implementations
  • Module08: Foundry Local toolkit with 10 comprehensive samples

External Dependencies

Project-Specific Notes

Module08 Sample Applications

The repository includes 10 comprehensive sample applications:

  1. 01-REST Chat Quickstart - Basic OpenAI SDK integration
  2. 02-OpenAI SDK Integration - Advanced SDK features
  3. 03-Model Discovery & Benchmarking - Model comparison tools
  4. 04-Chainlit RAG Application - Retrieval-augmented generation
  5. 05-Multi-Agent Orchestration - Basic agent coordination
  6. 06-Models-as-Tools Router - Intelligent model routing
  7. 07-Direct API Client - Low-level API integration
  8. 08-Windows 11 Chat App - Native Electron desktop application
  9. 09-Advanced Multi-Agent System - Complex agent orchestration
  10. 10-Foundry Tools Framework - LangChain/Semantic Kernel integration

Each sample demonstrates different aspects of edge AI development with Foundry Local.

Performance Considerations

  • SLMs are optimized for edge deployment (2-16GB RAM)
  • Local inference provides 50-500ms response times
  • Quantization techniques achieve 75% size reduction with 85% performance retention
  • Real-time conversation capabilities with local models

Security and Privacy

  • All processing happens locally - no data sent to cloud
  • Suitable for privacy-sensitive applications (healthcare, finance)
  • Meets data sovereignty requirements
  • Foundry Local runs entirely on local hardware

Getting Help

Documentation

Community Support

Contact

  • Maintainers: See CODEOWNERS
  • Security Issues: Follow responsible disclosure in SECURITY.md
  • Microsoft Support: For enterprise support, contact Microsoft customer service

Additional Resources

This is an educational repository focused on teaching Edge AI development. The primary contribution pattern is improving educational content and adding/enhancing sample applications that demonstrate Edge AI concepts.