{"owner":"microsoft","repo":"generative-ai-for-beginners","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n## Project Overview\n\nThis repository contains a comprehensive 21-lesson curriculum teaching Generative AI fundamentals and application development. The course is designed for beginners and covers everything from basic concepts to building production-ready applications.\n\n**Key Technologies:**\n- Python 3.9+ with libraries: `openai`, `python-dotenv`, `tiktoken`, `azure-ai-inference`, `pandas`, `numpy`, `matplotlib`\n- TypeScript/JavaScript with Node.js and libraries: `openai` (Azure OpenAI via the v1 endpoint + Responses API), `@azure-rest/ai-inference` (Microsoft Foundry Models)\n- Azure OpenAI Service, OpenAI API, and Microsoft Foundry Models (GitHub Models is retiring end of July 2026)\n- Jupyter Notebooks for interactive learning\n- Dev Containers for consistent development environment\n\n**Repository Structure:**\n- 21 numbered lesson directories (00-21) containing READMEs, code examples, and assignments\n- Multiple implementations: Python, TypeScript, and sometimes .NET examples\n- Translations directory with 40+ language versions\n- Centralized configuration via `.env` file (use `.env.copy` as template)\n\n## Setup Commands\n\n### Initial Repository Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/microsoft/generative-ai-for-beginners.git\ncd generative-ai-for-beginners\n\n# Copy environment template\ncp .env.copy .env\n# Edit .env with your API keys and endpoints\n```\n\n### Python Environment Setup\n\n```bash\n# Create virtual environment\npython3 -m venv venv\n\n# Activate virtual environment\n# On macOS/Linux:\nsource venv/bin/activate\n# On Windows:\nvenv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n### Node.js/TypeScript Setup\n\n```bash\n# Install root-level dependencies (for documentation tooling)\nnpm install\n\n# For individual lesson TypeScript examples, navigate to the specific lesson:\ncd 06-text-generation-apps/typescript/recipe-app\nnpm install\n```\n\n### Dev Container Setup (Recommended)\n\nThe repository includes a `.devcontainer` configuration for GitHub Codespaces or VS Code Dev Containers:\n\n1. Open repository in GitHub Codespaces or VS Code with Dev Containers extension\n2. Dev Container will automatically:\n   - Install Python dependencies from `requirements.txt`\n   - Run post-create script (`.devcontainer/post-create.sh`)\n   - Set up Jupyter kernel\n\n## Development Workflow\n\n### Environment Variables\n\nAll lessons requiring API access use environment variables defined in `.env`:\n\n- `OPENAI_API_KEY` - For OpenAI API\n- `AZURE_OPENAI_API_KEY` - For Azure OpenAI in Microsoft Foundry (Azure OpenAI Service is now part of Microsoft Foundry: https://ai.azure.com)\n- `AZURE_OPENAI_ENDPOINT` - Azure OpenAI endpoint URL (Foundry resource endpoint)\n- `AZURE_OPENAI_DEPLOYMENT` - Chat completion model deployment name (course default: `gpt-5-mini`)\n- `AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT` - Embeddings model deployment name (course default: `text-embedding-3-small`)\n- `AZURE_OPENAI_API_VERSION` - API version (default: `2024-10-21`)\n- `HUGGING_FACE_API_KEY` - For Hugging Face models\n- `AZURE_INFERENCE_ENDPOINT` - Microsoft Foundry Models endpoint (multi-provider model catalog)\n- `AZURE_INFERENCE_CREDENTIAL` - Microsoft Foundry Models API key (replaces the retiring `GITHUB_TOKEN`)\n- `AZURE_INFERENCE_CHAT_MODEL` - A non-reasoning model (e.g. `Llama-3.3-70B-Instruct`) used by the `temperature` examples, since reasoning models don't support sampling controls\n\n### Model conventions (important)\n\n- **Default chat model is `gpt-5-mini`** - a current, non-deprecated **reasoning** model. As of 2026 the older temperature-capable \"mini\" models (`gpt-4o-mini`, `gpt-4.1-mini`) are *deprecating*, so the curriculum standardizes on the GPT-5 family.\n- **Reasoning models reject `temperature` and `top_p`**, and use `max_output_tokens` (Responses API) / `max_completion_tokens` (chat completions) instead of `max_tokens`. Do **not** add `temperature`/`top_p`/`max_tokens` to samples that call `gpt-5-mini`.\n- **To demonstrate `temperature`**, samples use a **Llama** model (`Llama-3.3-70B-Instruct`) via the Microsoft Foundry Models endpoint (`AZURE_INFERENCE_CHAT_MODEL`). Steer reasoning models with prompt engineering + reasoning controls instead of sampling knobs.\n- **Fine-tuning (lesson 18)** keeps `gpt-4.1-mini`: GPT-5 only supports reinforcement fine-tuning (RFT), not the supervised fine-tuning (SFT) shown there.\n- Lessons 20 (Mistral) and 21 (Meta) keep `temperature`/`max_tokens` because they target Mistral/Llama models, which support them.\n\n### Running Python Examples\n\n```bash\n# Navigate to lesson directory\ncd 06-text-generation-apps/python\n\n# Run a Python script\npython aoai-app.py\n```\n\n### Running TypeScript Examples\n\n```bash\n# Navigate to TypeScript app directory\ncd 06-text-generation-apps/typescript/recipe-app\n\n# Build the TypeScript code\nnpm run build\n\n# Run the application\nnpm start\n```\n\n### Running Jupyter Notebooks\n\n```bash\n# Start Jupyter in the repository root\njupyter notebook\n\n# Or use VS Code with Jupyter extension\n```\n\n### Working with Different Lesson Types\n\n- **\"Learn\" lessons**: Focus on README.md documentation and concepts\n- **\"Build\" lessons**: Include working code examples in Python and TypeScript\n- Each lesson has a README.md with theory, code walkthroughs, and links to video content\n\n## Code Style Guidelines\n\n### Python\n\n- Use `python-dotenv` for environment variable management\n- Import `openai` library for API interactions\n- Use `pylint` for linting (some examples include `# pylint: disable=all` for simplicity)\n- Follow PEP 8 naming conventions\n- Store API credentials in `.env` file, never in code\n\n### TypeScript\n\n- Use `dotenv` package for environment variables\n- TypeScript configuration in `tsconfig.json` for each app\n- Use the `openai` package for Azure OpenAI (point the client at the `/openai/v1/` endpoint and call `client.responses.create`); use `@azure-rest/ai-inference` for Microsoft Foundry Models\n- Use `nodemon` for development with auto-reload\n- Build before running: `npm run build` then `npm start`\n\n### General Conventions\n\n- Keep code examples simple and educational\n- Include comments explaining key concepts\n- Each lesson's code should be self-contained and runnable\n- Use consistent naming: `aoai-` prefix for Azure OpenAI, `oai-` for OpenAI API, `githubmodels-` for Microsoft Foundry Models (legacy prefix retained from the GitHub Models era)\n\n## Documentation Guidelines\n\n### Markdown Style\n\n- All URLs must be wrapped in `[text](url)` format with no extra spaces\n- Relative links must start with `./` or `../`\n- All links to Microsoft domains must include tracking ID: `?WT.mc_id=academic-105485-koreyst`\n- No country-specific locales in URLs (avoid `/en-us/`)\n- Images stored in `./images` folder with descriptive names\n- Use English characters, numbers, and dashes in file names\n\n### Translation Support\n\n- Repository supports 40+ languages via automated GitHub Actions\n- Translations stored in `translations/` directory\n- Do not submit partial translations\n- Machine translations are not accepted\n- Translated images stored in `translated_images/` directory\n\n## Testing and Validation\n\n### Pre-submission Checks\n\nThis repository uses GitHub Actions for validation. Before submitting PRs:\n\n1. **Check Markdown Links**:\n   ```bash\n   # The validate-markdown.yml workflow checks:\n   # - Broken relative paths\n   # - Missing tracking IDs on paths\n   # - Missing tracking IDs on URLs\n   # - URLs with country locale\n   # - Broken external URLs\n   ```\n\n2. **Manual Testing**:\n   - Test Python examples: Activate venv and run scripts\n   - Test TypeScript examples: `npm install`, `npm run build`, `npm start`\n   - Verify environment variables are configured correctly\n   - Check that API keys work with the code examples\n\n3. **Code Examples**:\n   - Ensure all code runs without errors\n   - Test with both Azure OpenAI and OpenAI API when applicable\n   - Verify examples work with Microsoft Foundry Models where supported\n\n### No Automated Tests\n\nThis is an educational repository focused on tutorials and examples. There are no unit tests or integration tests to run. Validation is primarily:\n- Manual testing of code examples\n- GitHub Actions for Markdown validation\n- Community review of educational content\n\n## Pull Request Guidelines\n\n### Before Submitting\n\n1. Test code changes in both Python and TypeScript when applicable\n2. Run Markdown validation (triggered automatically on PR)\n3. Ensure tracking IDs are present on all Microsoft URLs\n4. Check that relative links are valid\n5. Verify images are properly referenced\n\n### PR Title Format\n\n- Use descriptive titles: `[Lesson 06] Fix Python example typo` or `Update README for lesson 08`\n- Reference issue numbers when applicable: `Fixes #123`\n\n### PR Description\n\n- Explain what was changed and why\n- Link to related issues\n- For code changes, specify which examples were tested\n- For translation PRs, include all files for a complete translation\n\n### Contribution Requirements\n\n- Sign Microsoft CLA (automatic on first PR)\n- Fork repository to your account before making changes\n- One PR per logical change (don't combine unrelated fixes)\n- Keep PRs focused and small when possible\n\n## Common Workflows\n\n### Adding a New Code Example\n\n1. Navigate to the appropriate lesson directory\n2. Create example in `python/` or `typescript/` subdirectory\n3. Follow naming convention: `{provider}-{example-name}.{py|ts|js}`\n4. Test with actual API credentials\n5. Document any new environment variables in lesson README\n\n### Updating Documentation\n\n1. Edit README.md in the lesson directory\n2. Follow Markdown guidelines (tracking IDs, relative links)\n3. Update translations are handled by GitHub Actions (don't edit manually)\n4. Test all links are valid\n\n### Working with Dev Containers\n\n1. Repository includes `.devcontainer/devcontainer.json`\n2. Post-create script installs Python dependencies automatically\n3. Extensions for Python and Jupyter are pre-configured\n4. Environment is based on `mcr.microsoft.com/devcontainers/universal:2.11.2`\n\n## Deployment and Publishing\n\nThis is a learning repository - there is no deployment process. The curriculum is consumed by:\n\n1. **GitHub Repository**: Direct access to code and documentation\n2. **GitHub Codespaces**: Instant dev environment with pre-configured setup\n3. **Microsoft Learn**: Content may be syndicated to official learning platform\n4. **docsify**: Documentation site built from Markdown (see `docsifytopdf.js` and `package.json`)\n\n### Building Documentation Site\n\n```bash\n# Generate PDF from documentation (if needed)\nnpm run convert\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Python Import Errors**:\n- Ensure virtual environment is activated\n- Run `pip install -r requirements.txt`\n- Check Python version is 3.9+\n\n**TypeScript Build Errors**:\n- Run `npm install` in the specific app directory\n- Check Node.js version is compatible\n- Clear `node_modules` and reinstall if needed\n\n**API Authentication Errors**:\n- Verify `.env` file exists and has correct values\n- Check API keys are valid and not expired\n- Ensure endpoint URLs are correct for your region\n\n**Missing Environment Variables**:\n- Copy `.env.copy` to `.env`\n- Fill in all required values for the lesson you're working on\n- Restart your application after updating `.env`\n\n## Additional Resources\n\n- [Course Setup Guide](./00-course-setup/README.md?WT.mc_id=academic-105485-koreyst)\n- [Contributing Guidelines](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Security Policy](./SECURITY.md)\n- [Azure AI Discord](https://aka.ms/genai-discord?WT.mc_id=academic-105485-koreyst)\n- [Collection of Advanced Code Samples](https://aka.ms/genai-beg-code?WT.mc_id=academic-105485-koreyst)\n\n## Project-Specific Notes\n\n- This is an **educational repository** focused on learning, not production code\n- Examples are intentionally simple and focused on teaching concepts\n- Code quality is balanced with educational clarity\n- Each lesson is self-contained and can be completed independently\n- The repository supports multiple API providers: Azure OpenAI, OpenAI, Microsoft Foundry Models, and offline providers such as Foundry Local and Ollama\n- Content is multilingual with automated translation workflows\n- Active community on Discord for questions and support\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n## Project Overview\n\nThis repository contains a comprehensive 21-lesson curriculum teaching Generative AI fundamentals and application development. The course is designed for beginners and covers everything from basic concepts to building production-ready applications.\n\n**Key Technologies:**\n- Python 3.9+ with libraries: `openai`, `python-dotenv`, `tiktoken`, `azure-ai-inference`, `pandas`, `numpy`, `matplotlib`\n- TypeScript/JavaScript with Node.js and libraries: `openai` (Azure OpenAI via the v1 endpoint + Responses API), `@azure-rest/ai-inference` (Microsoft Foundry Models)\n- Azure OpenAI Service, OpenAI API, and Microsoft Foundry Models (GitHub Models is retiring end of July 2026)\n- Jupyter Notebooks for interactive learning\n- Dev Containers for consistent development environment\n\n**Repository Structure:**\n- 21 numbered lesson directories (00-21) containing READMEs, code examples, and assignments\n- Multiple implementations: Python, TypeScript, and sometimes .NET examples\n- Translations directory with 40+ language versions\n- Centralized configuration via `.env` file (use `.env.copy` as template)\n\n## Setup Commands\n\n### Initial Repository Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/microsoft/generative-ai-for-beginners.git\ncd generative-ai-for-beginners\n\n# Copy environment template\ncp .env.copy .env\n# Edit .env with your API keys and endpoints\n```\n\n### Python Environment Setup\n\n```bash\n# Create virtual environment\npython3 -m venv venv\n\n# Activate virtual environment\n# On macOS/Linux:\nsource venv/bin/activate\n# On Windows:\nvenv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n### Node.js/TypeScript Setup\n\n```bash\n# Install root-level dependencies (for documentation tooling)\nnpm install\n\n# For individual lesson TypeScript examples, navigate to the specific lesson:\ncd 06-text-generation-apps/typescript/recipe-app\nnpm install\n```\n\n### Dev Container Setup (Recommended)\n\nThe repository includes a `.devcontainer` configuration for GitHub Codespaces or VS Code Dev Containers:\n\n1. Open repository in GitHub Codespaces or VS Code with Dev Containers extension\n2. Dev Container will automatically:\n   - Install Python dependencies from `requirements.txt`\n   - Run post-create script (`.devcontainer/post-create.sh`)\n   - Set up Jupyter kernel\n\n## Development Workflow\n\n### Environment Variables\n\nAll lessons requiring API access use environment variables defined in `.env`:\n\n- `OPENAI_API_KEY` - For OpenAI API\n- `AZURE_OPENAI_API_KEY` - For Azure OpenAI in Microsoft Foundry (Azure OpenAI Service is now part of Microsoft Foundry: https://ai.azure.com)\n- `AZURE_OPENAI_ENDPOINT` - Azure OpenAI endpoint URL (Foundry resource endpoint)\n- `AZURE_OPENAI_DEPLOYMENT` - Chat completion model deployment name (course default: `gpt-5-mini`)\n- `AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT` - Embeddings model deployment name (course default: `text-embedding-3-small`)\n- `AZURE_OPENAI_API_VERSION` - API version (default: `2024-10-21`)\n- `HUGGING_FACE_API_KEY` - For Hugging Face models\n- `AZURE_INFERENCE_ENDPOINT` - Microsoft Foundry Models endpoint (multi-provider model catalog)\n- `AZURE_INFERENCE_CREDENTIAL` - Microsoft Foundry Models API key (replaces the retiring `GITHUB_TOKEN`)\n- `AZURE_INFERENCE_CHAT_MODEL` - A non-reasoning model (e.g. `Llama-3.3-70B-Instruct`) used by the `temperature` examples, since reasoning models don't support sampling controls\n\n### Model conventions (important)\n\n- **Default chat model is `gpt-5-mini`** - a current, non-deprecated **reasoning** model. As of 2026 the older temperature-capable \"mini\" models (`gpt-4o-mini`, `gpt-4.1-mini`) are *deprecating*, so the curriculum standardizes on the GPT-5 family.\n- **Reasoning models reject `temperature` and `top_p`**, and use `max_output_tokens` (Responses API) / `max_completion_tokens` (chat completions) instead of `max_tokens`. Do **not** add `temperature`/`top_p`/`max_tokens` to samples that call `gpt-5-mini`.\n- **To demonstrate `temperature`**, samples use a **Llama** model (`Llama-3.3-70B-Instruct`) via the Microsoft Foundry Models endpoint (`AZURE_INFERENCE_CHAT_MODEL`). Steer reasoning models with prompt engineering + reasoning controls instead of sampling knobs.\n- **Fine-tuning (lesson 18)** keeps `gpt-4.1-mini`: GPT-5 only supports reinforcement fine-tuning (RFT), not the supervised fine-tuning (SFT) shown there.\n- Lessons 20 (Mistral) and 21 (Meta) keep `temperature`/`max_tokens` because they target Mistral/Llama models, which support them.\n\n### Running Python Examples\n\n```bash\n# Navigate to lesson directory\ncd 06-text-generation-apps/python\n\n# Run a Python script\npython aoai-app.py\n```\n\n### Running TypeScript Examples\n\n```bash\n# Navigate to TypeScript app directory\ncd 06-text-generation-apps/typescript/recipe-app\n\n# Build the TypeScript code\nnpm run build\n\n# Run the application\nnpm start\n```\n\n### Running Jupyter Notebooks\n\n```bash\n# Start Jupyter in the repository root\njupyter notebook\n\n# Or use VS Code with Jupyter extension\n```\n\n### Working with Different Lesson Types\n\n- **\"Learn\" lessons**: Focus on README.md documentation and concepts\n- **\"Build\" lessons**: Include working code examples in Python and TypeScript\n- Each lesson has a README.md with theory, code walkthroughs, and links to video content\n\n## Code Style Guidelines\n\n### Python\n\n- Use `python-dotenv` for environment variable management\n- Import `openai` library for API interactions\n- Use `pylint` for linting (some examples include `# pylint: disable=all` for simplicity)\n- Follow PEP 8 naming conventions\n- Store API credentials in `.env` file, never in code\n\n### TypeScript\n\n- Use `dotenv` package for environment variables\n- TypeScript configuration in `tsconfig.json` for each app\n- Use the `openai` package for Azure OpenAI (point the client at the `/openai/v1/` endpoint and call `client.responses.create`); use `@azure-rest/ai-inference` for Microsoft Foundry Models\n- Use `nodemon` for development with auto-reload\n- Build before running: `npm run build` then `npm start`\n\n### General Conventions\n\n- Keep code examples simple and educational\n- Include comments explaining key concepts\n- Each lesson's code should be self-contained and runnable\n- Use consistent naming: `aoai-` prefix for Azure OpenAI, `oai-` for OpenAI API, `githubmodels-` for Microsoft Foundry Models (legacy prefix retained from the GitHub Models era)\n\n## Documentation Guidelines\n\n### Markdown Style\n\n- All URLs must be wrapped in `[text](url)` format with no extra spaces\n- Relative links must start with `./` or `../`\n- All links to Microsoft domains must include tracking ID: `?WT.mc_id=academic-105485-koreyst`\n- No country-specific locales in URLs (avoid `/en-us/`)\n- Images stored in `./images` folder with descriptive names\n- Use English characters, numbers, and dashes in file names\n\n### Translation Support\n\n- Repository supports 40+ languages via automated GitHub Actions\n- Translations stored in `translations/` directory\n- Do not submit partial translations\n- Machine translations are not accepted\n- Translated images stored in `translated_images/` directory\n\n## Testing and Validation\n\n### Pre-submission Checks\n\nThis repository uses GitHub Actions for validation. Before submitting PRs:\n\n1. **Check Markdown Links**:\n   ```bash\n   # The validate-markdown.yml workflow checks:\n   # - Broken relative paths\n   # - Missing tracking IDs on paths\n   # - Missing tracking IDs on URLs\n   # - URLs with country locale\n   # - Broken external URLs\n   ```\n\n2. **Manual Testing**:\n   - Test Python examples: Activate venv and run scripts\n   - Test TypeScript examples: `npm install`, `npm run build`, `npm start`\n   - Verify environment variables are configured correctly\n   - Check that API keys work with the code examples\n\n3. **Code Examples**:\n   - Ensure all code runs without errors\n   - Test with both Azure OpenAI and OpenAI API when applicable\n   - Verify examples work with Microsoft Foundry Models where supported\n\n### No Automated Tests\n\nThis is an educational repository focused on tutorials and examples. There are no unit tests or integration tests to run. Validation is primarily:\n- Manual testing of code examples\n- GitHub Actions for Markdown validation\n- Community review of educational content\n\n## Pull Request Guidelines\n\n### Before Submitting\n\n1. Test code changes in both Python and TypeScript when applicable\n2. Run Markdown validation (triggered automatically on PR)\n3. Ensure tracking IDs are present on all Microsoft URLs\n4. Check that relative links are valid\n5. Verify images are properly referenced\n\n### PR Title Format\n\n- Use descriptive titles: `[Lesson 06] Fix Python example typo` or `Update README for lesson 08`\n- Reference issue numbers when applicable: `Fixes #123`\n\n### PR Description\n\n- Explain what was changed and why\n- Link to related issues\n- For code changes, specify which examples were tested\n- For translation PRs, include all files for a complete translation\n\n### Contribution Requirements\n\n- Sign Microsoft CLA (automatic on first PR)\n- Fork repository to your account before making changes\n- One PR per logical change (don't combine unrelated fixes)\n- Keep PRs focused and small when possible\n\n## Common Workflows\n\n### Adding a New Code Example\n\n1. Navigate to the appropriate lesson directory\n2. Create example in `python/` or `typescript/` subdirectory\n3. Follow naming convention: `{provider}-{example-name}.{py|ts|js}`\n4. Test with actual API credentials\n5. Document any new environment variables in lesson README\n\n### Updating Documentation\n\n1. Edit README.md in the lesson directory\n2. Follow Markdown guidelines (tracking IDs, relative links)\n3. Update translations are handled by GitHub Actions (don't edit manually)\n4. Test all links are valid\n\n### Working with Dev Containers\n\n1. Repository includes `.devcontainer/devcontainer.json`\n2. Post-create script installs Python dependencies automatically\n3. Extensions for Python and Jupyter are pre-configured\n4. Environment is based on `mcr.microsoft.com/devcontainers/universal:2.11.2`\n\n## Deployment and Publishing\n\nThis is a learning repository - there is no deployment process. The curriculum is consumed by:\n\n1. **GitHub Repository**: Direct access to code and documentation\n2. **GitHub Codespaces**: Instant dev environment with pre-configured setup\n3. **Microsoft Learn**: Content may be syndicated to official learning platform\n4. **docsify**: Documentation site built from Markdown (see `docsifytopdf.js` and `package.json`)\n\n### Building Documentation Site\n\n```bash\n# Generate PDF from documentation (if needed)\nnpm run convert\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Python Import Errors**:\n- Ensure virtual environment is activated\n- Run `pip install -r requirements.txt`\n- Check Python version is 3.9+\n\n**TypeScript Build Errors**:\n- Run `npm install` in the specific app directory\n- Check Node.js version is compatible\n- Clear `node_modules` and reinstall if needed\n\n**API Authentication Errors**:\n- Verify `.env` file exists and has correct values\n- Check API keys are valid and not expired\n- Ensure endpoint URLs are correct for your region\n\n**Missing Environment Variables**:\n- Copy `.env.copy` to `.env`\n- Fill in all required values for the lesson you're working on\n- Restart your application after updating `.env`\n\n## Additional Resources\n\n- [Course Setup Guide](./00-course-setup/README.md?WT.mc_id=academic-105485-koreyst)\n- [Contributing Guidelines](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Security Policy](./SECURITY.md)\n- [Azure AI Discord](https://aka.ms/genai-discord?WT.mc_id=academic-105485-koreyst)\n- [Collection of Advanced Code Samples](https://aka.ms/genai-beg-code?WT.mc_id=academic-105485-koreyst)\n\n## Project-Specific Notes\n\n- This is an **educational repository** focused on learning, not production code\n- Examples are intentionally simple and focused on teaching concepts\n- Code quality is balanced with educational clarity\n- Each lesson is self-contained and can be completed independently\n- The repository supports multiple API providers: Azure OpenAI, OpenAI, Microsoft Foundry Models, and offline providers such as Foundry Local and Ollama\n- Content is multilingual with automated translation workflows\n- Active community on Discord for questions and support\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n## Project Overview\n\nThis repository contains a comprehensive 21-lesson curriculum teaching Generative AI fundamentals and application development. The course is designed for beginners and covers everything from basic concepts to building production-ready applications.\n\n**Key Technologies:**\n- Python 3.9+ with libraries: `openai`, `python-dotenv`, `tiktoken`, `azure-ai-inference`, `pandas`, `numpy`, `matplotlib`\n- TypeScript/JavaScript with Node.js and libraries: `openai` (Azure OpenAI via the v1 endpoint + Responses API), `@azure-rest/ai-inference` (Microsoft Foundry Models)\n- Azure OpenAI Service, OpenAI API, and Microsoft Foundry Models (GitHub Models is retiring end of July 2026)\n- Jupyter Notebooks for interactive learning\n- Dev Containers for consistent development environment\n\n**Repository Structure:**\n- 21 numbered lesson directories (00-21) containing READMEs, code examples, and assignments\n- Multiple implementations: Python, TypeScript, and sometimes .NET examples\n- Translations directory with 40+ language versions\n- Centralized configuration via `.env` file (use `.env.copy` as template)\n\n## Setup Commands\n\n### Initial Repository Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/microsoft/generative-ai-for-beginners.git\ncd generative-ai-for-beginners\n\n# Copy environment template\ncp .env.copy .env\n# Edit .env with your API keys and endpoints\n```\n\n### Python Environment Setup\n\n```bash\n# Create virtual environment\npython3 -m venv venv\n\n# Activate virtual environment\n# On macOS/Linux:\nsource venv/bin/activate\n# On Windows:\nvenv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n### Node.js/TypeScript Setup\n\n```bash\n# Install root-level dependencies (for documentation tooling)\nnpm install\n\n# For individual lesson TypeScript examples, navigate to the specific lesson:\ncd 06-text-generation-apps/typescript/recipe-app\nnpm install\n```\n\n### Dev Container Setup (Recommended)\n\nThe repository includes a `.devcontainer` configuration for GitHub Codespaces or VS Code Dev Containers:\n\n1. Open repository in GitHub Codespaces or VS Code with Dev Containers extension\n2. Dev Container will automatically:\n   - Install Python dependencies from `requirements.txt`\n   - Run post-create script (`.devcontainer/post-create.sh`)\n   - Set up Jupyter kernel\n\n## Development Workflow\n\n### Environment Variables\n\nAll lessons requiring API access use environment variables defined in `.env`:\n\n- `OPENAI_API_KEY` - For OpenAI API\n- `AZURE_OPENAI_API_KEY` - For Azure OpenAI in Microsoft Foundry (Azure OpenAI Service is now part of Microsoft Foundry: https://ai.azure.com)\n- `AZURE_OPENAI_ENDPOINT` - Azure OpenAI endpoint URL (Foundry resource endpoint)\n- `AZURE_OPENAI_DEPLOYMENT` - Chat completion model deployment name (course default: `gpt-5-mini`)\n- `AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT` - Embeddings model deployment name (course default: `text-embedding-3-small`)\n- `AZURE_OPENAI_API_VERSION` - API version (default: `2024-10-21`)\n- `HUGGING_FACE_API_KEY` - For Hugging Face models\n- `AZURE_INFERENCE_ENDPOINT` - Microsoft Foundry Models endpoint (multi-provider model catalog)\n- `AZURE_INFERENCE_CREDENTIAL` - Microsoft Foundry Models API key (replaces the retiring `GITHUB_TOKEN`)\n- `AZURE_INFERENCE_CHAT_MODEL` - A non-reasoning model (e.g. `Llama-3.3-70B-Instruct`) used by the `temperature` examples, since reasoning models don't support sampling controls\n\n### Model conventions (important)\n\n- **Default chat model is `gpt-5-mini`** - a current, non-deprecated **reasoning** model. As of 2026 the older temperature-capable \"mini\" models (`gpt-4o-mini`, `gpt-4.1-mini`) are *deprecating*, so the curriculum standardizes on the GPT-5 family.\n- **Reasoning models reject `temperature` and `top_p`**, and use `max_output_tokens` (Responses API) / `max_completion_tokens` (chat completions) instead of `max_tokens`. Do **not** add `temperature`/`top_p`/`max_tokens` to samples that call `gpt-5-mini`.\n- **To demonstrate `temperature`**, samples use a **Llama** model (`Llama-3.3-70B-Instruct`) via the Microsoft Foundry Models endpoint (`AZURE_INFERENCE_CHAT_MODEL`). Steer reasoning models with prompt engineering + reasoning controls instead of sampling knobs.\n- **Fine-tuning (lesson 18)** keeps `gpt-4.1-mini`: GPT-5 only supports reinforcement fine-tuning (RFT), not the supervised fine-tuning (SFT) shown there.\n- Lessons 20 (Mistral) and 21 (Meta) keep `temperature`/`max_tokens` because they target Mistral/Llama models, which support them.\n\n### Running Python Examples\n\n```bash\n# Navigate to lesson directory\ncd 06-text-generation-apps/python\n\n# Run a Python script\npython aoai-app.py\n```\n\n### Running TypeScript Examples\n\n```bash\n# Navigate to TypeScript app directory\ncd 06-text-generation-apps/typescript/recipe-app\n\n# Build the TypeScript code\nnpm run build\n\n# Run the application\nnpm start\n```\n\n### Running Jupyter Notebooks\n\n```bash\n# Start Jupyter in the repository root\njupyter notebook\n\n# Or use VS Code with Jupyter extension\n```\n\n### Working with Different Lesson Types\n\n- **\"Learn\" lessons**: Focus on README.md documentation and concepts\n- **\"Build\" lessons**: Include working code examples in Python and TypeScript\n- Each lesson has a README.md with theory, code walkthroughs, and links to video content\n\n## Code Style Guidelines\n\n### Python\n\n- Use `python-dotenv` for environment variable management\n- Import `openai` library for API interactions\n- Use `pylint` for linting (some examples include `# pylint: disable=all` for simplicity)\n- Follow PEP 8 naming conventions\n- Store API credentials in `.env` file, never in code\n\n### TypeScript\n\n- Use `dotenv` package for environment variables\n- TypeScript configuration in `tsconfig.json` for each app\n- Use the `openai` package for Azure OpenAI (point the client at the `/openai/v1/` endpoint and call `client.responses.create`); use `@azure-rest/ai-inference` for Microsoft Foundry Models\n- Use `nodemon` for development with auto-reload\n- Build before running: `npm run build` then `npm start`\n\n### General Conventions\n\n- Keep code examples simple and educational\n- Include comments explaining key concepts\n- Each lesson's code should be self-contained and runnable\n- Use consistent naming: `aoai-` prefix for Azure OpenAI, `oai-` for OpenAI API, `githubmodels-` for Microsoft Foundry Models (legacy prefix retained from the GitHub Models era)\n\n## Documentation Guidelines\n\n### Markdown Style\n\n- All URLs must be wrapped in `[text](url)` format with no extra spaces\n- Relative links must start with `./` or `../`\n- All links to Microsoft domains must include tracking ID: `?WT.mc_id=academic-105485-koreyst`\n- No country-specific locales in URLs (avoid `/en-us/`)\n- Images stored in `./images` folder with descriptive names\n- Use English characters, numbers, and dashes in file names\n\n### Translation Support\n\n- Repository supports 40+ languages via automated GitHub Actions\n- Translations stored in `translations/` directory\n- Do not submit partial translations\n- Machine translations are not accepted\n- Translated images stored in `translated_images/` directory\n\n## Testing and Validation\n\n### Pre-submission Checks\n\nThis repository uses GitHub Actions for validation. Before submitting PRs:\n\n1. **Check Markdown Links**:\n   ```bash\n   # The validate-markdown.yml workflow checks:\n   # - Broken relative paths\n   # - Missing tracking IDs on paths\n   # - Missing tracking IDs on URLs\n   # - URLs with country locale\n   # - Broken external URLs\n   ```\n\n2. **Manual Testing**:\n   - Test Python examples: Activate venv and run scripts\n   - Test TypeScript examples: `npm install`, `npm run build`, `npm start`\n   - Verify environment variables are configured correctly\n   - Check that API keys work with the code examples\n\n3. **Code Examples**:\n   - Ensure all code runs without errors\n   - Test with both Azure OpenAI and OpenAI API when applicable\n   - Verify examples work with Microsoft Foundry Models where supported\n\n### No Automated Tests\n\nThis is an educational repository focused on tutorials and examples. There are no unit tests or integration tests to run. Validation is primarily:\n- Manual testing of code examples\n- GitHub Actions for Markdown validation\n- Community review of educational content\n\n## Pull Request Guidelines\n\n### Before Submitting\n\n1. Test code changes in both Python and TypeScript when applicable\n2. Run Markdown validation (triggered automatically on PR)\n3. Ensure tracking IDs are present on all Microsoft URLs\n4. Check that relative links are valid\n5. Verify images are properly referenced\n\n### PR Title Format\n\n- Use descriptive titles: `[Lesson 06] Fix Python example typo` or `Update README for lesson 08`\n- Reference issue numbers when applicable: `Fixes #123`\n\n### PR Description\n\n- Explain what was changed and why\n- Link to related issues\n- For code changes, specify which examples were tested\n- For translation PRs, include all files for a complete translation\n\n### Contribution Requirements\n\n- Sign Microsoft CLA (automatic on first PR)\n- Fork repository to your account before making changes\n- One PR per logical change (don't combine unrelated fixes)\n- Keep PRs focused and small when possible\n\n## Common Workflows\n\n### Adding a New Code Example\n\n1. Navigate to the appropriate lesson directory\n2. Create example in `python/` or `typescript/` subdirectory\n3. Follow naming convention: `{provider}-{example-name}.{py|ts|js}`\n4. Test with actual API credentials\n5. Document any new environment variables in lesson README\n\n### Updating Documentation\n\n1. Edit README.md in the lesson directory\n2. Follow Markdown guidelines (tracking IDs, relative links)\n3. Update translations are handled by GitHub Actions (don't edit manually)\n4. Test all links are valid\n\n### Working with Dev Containers\n\n1. Repository includes `.devcontainer/devcontainer.json`\n2. Post-create script installs Python dependencies automatically\n3. Extensions for Python and Jupyter are pre-configured\n4. Environment is based on `mcr.microsoft.com/devcontainers/universal:2.11.2`\n\n## Deployment and Publishing\n\nThis is a learning repository - there is no deployment process. The curriculum is consumed by:\n\n1. **GitHub Repository**: Direct access to code and documentation\n2. **GitHub Codespaces**: Instant dev environment with pre-configured setup\n3. **Microsoft Learn**: Content may be syndicated to official learning platform\n4. **docsify**: Documentation site built from Markdown (see `docsifytopdf.js` and `package.json`)\n\n### Building Documentation Site\n\n```bash\n# Generate PDF from documentation (if needed)\nnpm run convert\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Python Import Errors**:\n- Ensure virtual environment is activated\n- Run `pip install -r requirements.txt`\n- Check Python version is 3.9+\n\n**TypeScript Build Errors**:\n- Run `npm install` in the specific app directory\n- Check Node.js version is compatible\n- Clear `node_modules` and reinstall if needed\n\n**API Authentication Errors**:\n- Verify `.env` file exists and has correct values\n- Check API keys are valid and not expired\n- Ensure endpoint URLs are correct for your region\n\n**Missing Environment Variables**:\n- Copy `.env.copy` to `.env`\n- Fill in all required values for the lesson you're working on\n- Restart your application after updating `.env`\n\n## Additional Resources\n\n- [Course Setup Guide](./00-course-setup/README.md?WT.mc_id=academic-105485-koreyst)\n- [Contributing Guidelines](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Security Policy](./SECURITY.md)\n- [Azure AI Discord](https://aka.ms/genai-discord?WT.mc_id=academic-105485-koreyst)\n- [Collection of Advanced Code Samples](https://aka.ms/genai-beg-code?WT.mc_id=academic-105485-koreyst)\n\n## Project-Specific Notes\n\n- This is an **educational repository** focused on learning, not production code\n- Examples are intentionally simple and focused on teaching concepts\n- Code quality is balanced with educational clarity\n- Each lesson is self-contained and can be completed independently\n- The repository supports multiple API providers: Azure OpenAI, OpenAI, Microsoft Foundry Models, and offline providers such as Foundry Local and Ollama\n- Content is multilingual with automated translation workflows\n- Active community on Discord for questions and support\n","category":"root","tokens":3072}]}