generative-ai-for-beginners / ur

# AGENTS.md

## پروجیکٹ کا جائزہ

اس ریپوزیٹری میں 21 اسباق پر مشتمل جامع نصاب شامل ہے جو جنریٹو AI کے بنیادی اصول اور ایپلیکیشن کی ترقی سکھاتا ہے۔ یہ کورس ابتدائی افراد کے لیے ڈیزائن کیا گیا ہے اور بنیادی تصورات سے لے کر پیداواری طور پر تیار ایپس بنانے تک ہر چیز کو شامل کرتا ہے۔

**اہم ٹیکنالوجیز:**
- پائتھن 3.9+ لائبریریوں کے ساتھ: `openai`، `python-dotenv`، `tiktoken`، `azure-ai-inference`، `pandas`، `numpy`، `matplotlib`
- ٹائپ اسکرپٹ/جاوا اسکرپٹ Node.js اور لائبریریوں کے ساتھ: `openai` (Azure OpenAI v1 اینڈپوائنٹ + Responses API کے ذریعے)، `@azure-rest/ai-inference` (Microsoft Foundry Models)
- Azure OpenAI سروس، OpenAI API، اور Microsoft Foundry Models (GitHub Models جولائی 2026 کے آخر میں بند ہو رہا ہے)
- انٹریکٹو سیکھنے کے لیے Jupyter نوٹ بکس
- مستقل ترقیاتی ماحول کے لیے Dev Containers

**ریپوزیٹری کی ساخت:**
- 21 نمبر والے اسباق کی ڈائریکٹریز (00-21) جن میں README، کوڈ مثالیں، اور اسائنمنٹس شامل ہیں
- متعدد امپلیمینٹیشنز: پائتھن، ٹائپ اسکرپٹ، اور بعض اوقات .NET کی مثالیں
- 40+ زبانوں میں تراجم کی ڈائریکٹری
- مرکزی کنفیگریشن `.env` فائل کے ذریعے (ٹیمپلیٹ کے طور پر `.env.copy` استعمال کریں)

## سیٹ اپ کمانڈز

### ابتدائی ریپوزیٹری کی ترتیب

```bash
# مخزن کی نقل تیار کریں
git clone https://github.com/microsoft/generative-ai-for-beginners.git
cd generative-ai-for-beginners

# ماحول کا سانچہ کاپی کریں
cp .env.copy .env
# .env کو اپنے API کیز اور اینڈ پوائنٹس کے ساتھ ترمیم کریں
```

### پائتھن ماحول کا سیٹ اپ

```bash
# ورچوئل ماحول بنائیں
python3 -m venv venv

# ورچوئل ماحول کو فعال کریں
# میک او ایس / لینکس پر:
source venv/bin/activate
# ونڈوز پر:
venv\Scripts\activate

# منحصر چیزیں انسٹال کریں
pip install -r requirements.txt
```

### Node.js/TypeScript کا سیٹ اپ

```bash
# روٹ لیول کی dependencies انسٹال کریں (دستاویز سازی کے ٹولز کے لیے)
npm install

# انفرادی سبق TypeScript کی مثالوں کے لیے، مخصوص سبق پر جائیں:
cd 06-text-generation-apps/typescript/recipe-app
npm install
```

### Dev Container کا سیٹ اپ (تجویز کردہ)

ریپوزیٹری میں GitHub Codespaces یا VS Code Dev Containers کے لیے `.devcontainer` کی کنفیگریشن شامل ہے:

1. GitHub Codespaces میں ریپوزیٹری کھولیں یا VS Code میں Dev Containers ایکسٹینشن کے ساتھ
2. Dev Container خود بخود:
   - `requirements.txt` سے پائتھن انحصار انسٹال کرے گا
   - پوسٹ-کریئٹ اسکرپٹ چلائے گا (`.devcontainer/post-create.sh`)
   - Jupyter کرنل سیٹ اپ کرے گا

## ترقیاتی ورک فلو

### ماحول کی متغیرات (Environment Variables)

تمام اسباق جو API تک رسائی چاہتے ہیں وہ `.env` فائل میں متعین ماحولیاتی متغیرات استعمال کرتے ہیں:

- `OPENAI_API_KEY` - OpenAI API کے لیے
- `AZURE_OPENAI_API_KEY` - Microsoft Foundry (Azure OpenAI سروس کا حصہ) میں Azure OpenAI کے لیے (https://ai.azure.com)
- `AZURE_OPENAI_ENDPOINT` - Azure OpenAI اینڈپوائنٹ URL (Foundry ریسورس اینڈپوائنٹ)
- `AZURE_OPENAI_DEPLOYMENT` - چیٹ کمپلیشن ماڈل کی تعیناتی کا نام (کورس کی ڈیفالٹ: `gpt-5-mini`)
- `AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT` - ایمبیڈنگ ماڈل کی تعیناتی کا نام (کورس کی ڈیفالٹ: `text-embedding-3-small`)
- `AZURE_OPENAI_API_VERSION` - API ورژن (ڈیفالٹ: `2024-10-21`)
- `HUGGING_FACE_API_KEY` - Hugging Face ماڈلز کے لیے
- `AZURE_INFERENCE_ENDPOINT` - Microsoft Foundry Models اینڈپوائنٹ (کئی فراہم کنندگان کا ماڈل کیٹلاگ)
- `AZURE_INFERENCE_CREDENTIAL` - Microsoft Foundry Models API کی کلید (متبادل `GITHUB_TOKEN` جو بند ہو رہا ہے)
- `AZURE_INFERENCE_CHAT_MODEL` - ایک غیر استدلالی ماڈل (مثلاً `Llama-3.3-70B-Instruct`) جو `temperature` مثالوں میں استعمال ہوتا ہے، کیونکہ استدلالی ماڈلز سیمپلنگ کنٹرولز کو سپورٹ نہیں کرتے

### ماڈل کے قواعد و ضوابط (اہم)

- **ڈیفالٹ چیٹ ماڈل `gpt-5-mini` ہے** - ایک موجودہ، غیر منسوخ شدہ **استدلال** ماڈل۔ 2026 سے پرانے temperature-قابل "mini" ماڈلز (`gpt-4o-mini`, `gpt-4.1-mini`) *ختم ہو رہے ہیں*، اس لیے نصاب GPT-5 فیملی پر معیاری ہے۔
- **استدلالی ماڈلز `temperature` اور `top_p` قبول نہیں کرتے**، اور `max_output_tokens` (Responses API) / `max_completion_tokens` (chat completions) استعمال کرتے ہیں بجائے `max_tokens` کے۔ `gpt-5-mini` کو کال کرنے والی مثالوں میں `temperature`/`top_p`/`max_tokens` شامل نہ کریں۔
- **`temperature` دکھانے کے لیے**، مثالیں ایک **Llama** ماڈل (`Llama-3.3-70B-Instruct`) استعمال کرتی ہیں Microsoft Foundry Models اینڈپوائنٹ (`AZURE_INFERENCE_CHAT_MODEL`) کے ذریعے۔ استدلالی ماڈلز کو سیمپلنگ نوبز کے بجائے پرومپٹ انجینیئرنگ اور استدلالی کنٹرولز سے ہدایت دیں۔
- **فائن ٹیوننگ (سبق 18)** `gpt-4.1-mini` رکھتا ہے: GPT-5 صرف reinforcement fine-tuning (RFT) کو سپورٹ کرتا ہے، نہ کہ supervised fine-tuning (SFT) جیسا کہ وہاں دکھایا گیا ہے۔
- اسباق 20 (Mistral) اور 21 (Meta) `temperature`/`max_tokens` رکھتے ہیں کیونکہ وہ Mistral/Llama ماڈلز کو ہدف بناتے ہیں جو انہیں سپورٹ کرتے ہیں۔

### پائتھن مثالیں چلانا

```bash
# سبق کے فولڈر پر جائیں
cd 06-text-generation-apps/python

# ایک پائتھن اسکرپٹ چلائیں
python aoai-app.py
```

### ٹائپ اسکرپٹ مثالیں چلانا

```bash
# ٹائپ اسکرپٹ ایپ کے ڈائریکٹری پر جائیں
cd 06-text-generation-apps/typescript/recipe-app

# ٹائپ اسکرپٹ کوڈ بنائیں
npm run build

# ایپلیکیشن چلائیں
npm start
```

### Jupyter نوٹ بکس چلانا

```bash
# ذخیرہ بذریعہ روٹ میں Jupyter شروع کریں
jupyter notebook

# یا Jupyter ایکسٹینشن کے ساتھ VS Code استعمال کریں
```

### مختلف قسم کے اسباق کے ساتھ کام کرنا

- **"سیکھنے" والے اسباق**: README.md ڈاکیومنٹیشن اور تصورات پر توجہ
- **"بنانے" والے اسباق**: پائتھن اور ٹائپ اسکرپٹ میں کام کرتے ہوئے کوڈ کی مثالیں شامل
- ہر سبق کا README.md ہوتا ہے جس میں نظریہ، کوڈ واک تھروز، اور ویڈیو مواد کے لنکس شامل ہوتے ہیں

## کوڈ سٹائل گائیڈ لائنز

### پائتھن

- ماحول کی متغیرات کے انتظام کے لیے `python-dotenv` استعمال کریں
- API تعاملات کے لیے `openai` لائبریری امپورٹ کریں
- کوڈ میں linting کے لیے `pylint` استعمال کریں (کچھ مثالوں میں سادگی کے لیے `# pylint: disable=all` شامل ہے)
- PEP 8 نام کاری کے اصولوں کی پیروی کریں
- API اسناد `.env` فائل میں محفوظ کریں، کوڈ میں کبھی نہیں

### ٹائپ اسکرپٹ

- ماحول کی متغیرات کے لیے `dotenv` پیکج استعمال کریں
- ہر ایپ کے لیے `tsconfig.json` میں ٹائپ اسکرپٹ سیٹ اپ
- Azure OpenAI کے لیے `openai` پیکج استعمال کریں (کلائنٹ کو `/openai/v1/` اینڈپوائنٹ کی جانب اشارہ کریں اور `client.responses.create` کال کریں)؛ Microsoft Foundry Models کے لیے `@azure-rest/ai-inference` استعمال کریں
- ترقی کے دوران خودکار ری لوڈ کے لیے `nodemon` استعمال کریں
- چلانے سے پہلے بنائیں: `npm run build` پھر `npm start`

### عمومی اصول

- کوڈ کی مثالیں آسان اور تعلیمی رکھیں
- کلیدی تصورات کی وضاحت کرنے والے کمنٹس شامل کریں
- ہر سبق کا کوڈ خود مختار اور چلنے کے قابل ہو
- مستقل نام کاری استعمال کریں: Azure OpenAI کے لیے `aoai-`، OpenAI API کے لیے `oai-`، Microsoft Foundry Models کے لیے `githubmodels-` (GitHub Models کے دور کی پرانی اصطلاح برقرار)

## دستاویزات کے اصول

### مارکڈاؤن اسٹائل

- تمام URLs کو `[text](../../url)` فارمیٹ میں بغیر اضافی خالی جگہ کے لپیٹنا ضروری ہے
- ریلیٹو لنکس کا آغاز `./` یا `../` سے ہونا چاہیے
- مائیکروسافٹ ڈومینز کے تمام لنکس میں ٹریکنگ ID شامل ہونا ضروری ہے: `?WT.mc_id=academic-105485-koreyst`
- URLs میں مخدوش مقامی زبانوں سے گریز کریں (جیسے `/en-us/`)
- تصاویر `./images` فولڈر میں وضاحتی ناموں کے ساتھ ذخیرہ ہوں
- فائل ناموں میں انگریزی حروف، اعداد، اور ڈیشز استعمال کریں

### ترجمے کی مدد

- ریپوزیٹری 40+ زبانوں کی خودکار GitHub Actions کے ذریعے مدد حاصل کرتی ہے
- تراجم `translations/` ڈائریکٹری میں محفوظ ہوتے ہیں
- جزوی تراجم جمع کروائیں نہیں
- مشین تراجم قبول نہیں کیے جاتے
- ترجمہ شدہ تصاویر `translated_images/` ڈائریکٹری میں محفوظ ہوں

## ٹیسٹنگ اور تصدیق

### پیشگی چیکس

یہ ریپوزیٹری صلاحیت کیلئے GitHub Actions استعمال کرتی ہے۔ PR جمع کروانے سے پہلے:

1. **مارکڈاؤن لنکس چیک کریں**:
   ```bash
   # validate-markdown.yml ورک فلو جانچتا ہے:
   # - خراب نسبتاً راستے
   # - راستوں پر گمشدہ ٹریکنگ آئی ڈیز
   # - URLs پر گمشدہ ٹریکنگ آئی ڈیز
   # - ملک کے لوکل کے ساتھ URLs
   # - خراب بیرونی URLs
   ```

2. **دستی ٹیسٹنگ**:
   - پائتھن کی مثالیں آزمائیں: وینو فعال کریں اور اسکرپٹس چلائیں
   - ٹائپ اسکرپٹ کی مثالیں آزمائیں: `npm install`, `npm run build`, `npm start`
   - محیطی متغیرات درست ترتیب میں ہیں اس کی تصدیق کریں
   - کوڈ مثالوں کے ساتھ API کیز کام کر رہی ہیں وہ چیک کریں

3. **کوڈ مثالیں**:
   - یقینی بنائیں کہ تمام کوڈ بغیر غلطی کے چلے
   - جہاں قابل اطلاق ہو Azure OpenAI اور OpenAI API دونوں کے ساتھ ٹیسٹ کریں
   - جہاں سپورٹ ہو Microsoft Foundry Models کے ساتھ مثالیں کام کرتی ہیں اس کی تصدیق کریں

### کوئی خودکار ٹیسٹ نہیں

یہ تعلیمی ریپوزیٹری ہے جس میں ٹیوٹوریلز اور مثالیں شامل ہیں۔ کوئی یونٹ ٹیسٹ یا انٹیگریشن ٹیسٹ نہیں ہوتے۔ تصدیق بنیادی طور پر:
- کوڈ کی مثالوں کی دستی جانچ
- مارکڈاؤن کی تصدیق کے لیے GitHub Actions
- تعلیمی مواد کے لیے کمیونٹی جائزہ

## پل ریکویسٹ گائیڈ لائنز

### جمع کروانے سے پہلے

1. پائتھن اور ٹائپ اسکرپٹ دونوں میں کوڈ کی تبدیلیاں آزمانا جہاں قابل اطلاق ہو
2. مارکڈاؤن کی تصدیق چلانا (خودکار طور پر PR پر شروع ہوتی ہے)
3. تمام Microsoft URLs پر ٹریکنگ IDS موجود ہونا یقینی بنائیں
4. یقینی بنائیں کہ ریلیٹو لنکس درست ہیں
5. چیک کریں کہ تصاویر مناسب طریقے سے حوالہ دی گئی ہیں

### PR عنوان کا فارمیٹ

- تشریحی عنوان استعمال کریں: `[Lesson 06] Fix Python example typo` یا `Update README for lesson 08`
- جہاں مناسب ہو مسئلہ نمبر شامل کریں: `Fixes #123`

### PR کی تفصیل

- واضح کریں کہ کیا بدلا اور کیوں
- متعلقہ مسائل کے لنکس دیں
- کوڈ تبدیلیوں کے لیے وضاحت کریں کہ کونسی مثالوں کی جانچ کی گئی
- ترجمہ PRs کے لیے، مکمل ترجمہ کے لیے تمام فائلیں شامل کریں

### شراکت کی ضروریات

- Microsoft CLA پر دستخط کریں (پہلے PR پر خودکار)
- تبدیلیاں کرنے سے پہلے ریپوزیٹری کو اپنے اکاؤنٹ میں فورک کریں
- منطقی تبدیلی کے لیے ایک PR (غیر متعلقہ اصلاحات نہ ملائیں)
- PRs کو ممکن ہو تو چھوٹے اور مرکوز رکھیں

## عمومی ورک فلو

### نیا کوڈ مثال شامل کرنا

1. متعلقہ سبق کی ڈائریکٹری میں جائیں
2. `python/` یا `typescript/` سب ڈائریکٹری میں مثال بنائیں
3. نام کاری طریقہ کار کی پیروی کریں: `{provider}-{example-name}.{py|ts|js}`
4. اصل API اسناد کے ساتھ ٹیسٹ کریں
5. سبق کے README میں نئی ماحول کی متغیرات کو دستاویزی بنائیں

### دستاویزات کی تازہ کاری

1. سبق کی ڈائریکٹری میں README.md میں ترمیم کریں
2. مارکڈاؤن اصولوں کی پیروی کریں (ٹریکنگ IDs، ریلیٹو لنکس)
3. ترجمہ خودکار GitHub Actions کے ذریعے ہینڈل ہوتے ہیں (دستی ترمیم نہ کریں)
4. تمام لنکس کی درستگی کو چیک کریں

### Dev Containers کے ساتھ کام کرنا

1. ریپوزیٹری میں `.devcontainer/devcontainer.json` شامل ہے
2. پوسٹ-کریئٹ اسکرپٹ خود بخود پائتھن انحصار انسٹال کرتا ہے
3. پائتھن اور Jupyter کے لیے ایکسٹینشنز پہلے سے ترتیب دی گئی ہیں
4. ماحول `mcr.microsoft.com/devcontainers/universal:2.11.2` پر مبنی ہے

## ڈیپلائمنٹ اور شائع کرنا

یہ تعلیمی ریپوزیٹری ہے - کوئی تعیناتی کا عمل نہیں ہے۔ نصاب درج ذیل طریقوں سے استعمال ہوتا ہے:

1. **GitHub ریپوزیٹری**: کوڈ اور دستاویزات تک براہِ راست رسائی
2. **GitHub Codespaces**: پہلے سے ترتیب شدہ فوری ترقیاتی ماحول
3. **Microsoft Learn**: مواد کو سرکاری لرننگ پلیٹ فارم پر بھیجنا ممکن ہے
4. **docsify**: مارکڈاؤن سے دستاویزاتی سائٹ بنائی گئی (دیکھیں `docsifytopdf.js` اور `package.json`)

### دستاویزی سائٹ بنانا

```bash
# ڈاکیومنٹیشن سے PDF تیار کریں (اگر ضرورت ہو)
npm run convert
```

## مسائل کا حل

### عمومی مسائل

**پائتھن درآمدی غلطیاں**:
- یقینی بنائیں کہ ورچوئل ماحول فعال ہے
- `pip install -r requirements.txt` چلائیں
- پائتھن ورژن 3.9+ درست ہے چیک کریں

**ٹائپ اسکرپٹ کی تعمیر کی غلطیاں**:
- مخصوص ایپ ڈائریکٹری میں `npm install` چلائیں
- Node.js ورژن کی مطابقت چیک کریں
- `node_modules` صاف کریں اور اگر ضرورت ہو دوبارہ انسٹال کریں

**API توثیقی غلطیاں**:
- `.env` فائل موجود اور درست اقدار والی ہے اس کی جانچ کریں
- API کیز درست اور ختم نہ ہوئی ہوں اس کا یقین کریں
- اینڈپوائنٹ URLs آپ کے علاقے کے لیے درست ہیں اس کا اندراج کریں

**ماحولیاتی متغیرات غائب ہیں**:
- `.env.copy` کو `.env` میں کاپی کریں
- کام کر رہے سبق کے لیے تمام مطلوبہ اقدار پر کریں
- `.env` کی اپڈیٹ کے بعد اپنی ایپلیکیشن دوبارہ شروع کریں

## اضافی وسائل

- [کورس سیٹ اپ گائیڈ](./00-course-setup/README.md?WT.mc_id=academic-105485-koreyst)
- [شراکت داری کی ہدایات](./CONTRIBUTING.md)
- [ضابطہ اخلاق](./CODE_OF_CONDUCT.md)
- [سیکیورٹی پالیسی](./SECURITY.md)
- [Azure AI Discord](https://aka.ms/genai-discord?WT.mc_id=academic-105485-koreyst)
- [جدید کوڈ نمونوں کا مجموعہ](https://aka.ms/genai-beg-code?WT.mc_id=academic-105485-koreyst)

## پروجیکٹ سے متعلق نوٹس

- یہ ایک **تعلیمی ریپوزیٹری** ہے جو سیکھنے پر مرکوز ہے، پیداواری کوڈ نہیں
- مثالیں جان بوجھ کر سادہ اور تصورات کی تعلیم پر توجہ مرکوز ہیں
- کوڈ کی معیار تعلیمی وضاحت کے ساتھ توازن میں ہے
- ہر سبق خود مختار ہے اور آزادانہ طور پر مکمل کیا جا سکتا ہے
- ریپوزیٹری متعدد API فراہم کنندگان کی مدد کرتا ہے: Azure OpenAI، OpenAI، Microsoft Foundry Models، اور آف لائن فراہم کنندگان جیسے Foundry Local اور Ollama
- مواد کثیر لسانی ہے اور خودکار ترجمے کے ورک فلو کے ساتھ
- سوالات اور مدد کے لیے Discord پر فعال کمیونٹی

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**ڈس کلیمر**:
یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔
<!-- CO-OP TRANSLATOR DISCLAIMER END -->