generative-ai-for-beginners / bn

# AGENTS.md

## প্রকল্পের সারসংক্ষেপ

এই রেপোজিটরিতে রয়েছে ২১টি পাঠের বিস্তৃত পাঠ্যক্রম যা জেনারেটিভ AI-এর মূল বিষয়বস্তু এবং অ্যাপ্লিকেশন উন্নয়ন শেখায়। কোর্সটি নতুনদের জন্য ডিজাইন করা হয়েছে এবং বেসিক ধারণা থেকে শুরু করে প্রোডাকশন-রেডি অ্যাপ্লিকেশন তৈরি পর্যন্ত সবকিছু আচ্ছাদিত করে।

**মূল প্রযুক্তি:**
- Python 3.9+ লাইব্রেরিসহ: `openai`, `python-dotenv`, `tiktoken`, `azure-ai-inference`, `pandas`, `numpy`, `matplotlib`
- TypeScript/JavaScript Node.js এবং লাইব্রেরিসহ: `openai` (Azure OpenAI v1 endpoint + Responses API), `@azure-rest/ai-inference` (Microsoft Foundry Models)
- Azure OpenAI সার্ভিস, OpenAI API, এবং Microsoft Foundry Models (GitHub Models ২০২৬ সালের জুলাই শেষে বন্ধ হচ্ছে)
- ইন্টারঅ্যাকটিভ শিক্ষার জন্য Jupyter Notebooks
- ধারাবাহিক উন্নয়নের জন্য Dev Containers

**রেপোজিটরি স্ট্রাকচার:**
- ২১টি নম্বরড পাঠ ডিরেক্টরি (০০-২১) যা README, কোড উদাহরণ এবং অ্যাসাইনমেন্টসমূহ ধারণ করে
- একাধিক ইমপ্লিমেন্টেশন: Python, TypeScript, এবং কিছু সময়ে .NET উদাহরণ
- অনুবাদ ডিরেক্টরি যেখানে ৪০+ ভাষার সংস্করণ আছে
- `.env` ফাইলের মাধ্যমে কেন্দ্রীভূত কনফিগারেশন (টেমপ্লেট হিসাবে `.env.copy` ব্যবহার করুন)

## সেটআপ কমান্ডসমূহ

### প্রাথমিক রেপোজিটরি সেটআপ

```bash
# রেপোসিটরি ক্লোন করুন
git clone https://github.com/microsoft/generative-ai-for-beginners.git
cd generative-ai-for-beginners

# পরিবেশ টেমপ্লেট কপি করুন
cp .env.copy .env
# আপনার API কী এবং এন্ডপয়েন্ট দিয়ে .env সম্পাদনা করুন
```

### Python এনভায়রনমেন্ট সেটআপ

```bash
# ভার্চুয়াল পরিবেশ তৈরি করুন
python3 -m venv venv

# ভার্চুয়াল পরিবেশ সক্রিয় করুন
# ম্যাকওএস/লিনাক্স-এ:
source venv/bin/activate
# উইন্ডোজ-এ:
venv\Scripts\activate

# নির্ভরশীলতাগুলি ইনস্টল করুন
pip install -r requirements.txt
```

### Node.js/TypeScript সেটআপ

```bash
# রুট-লেভেল নির্ভরতাসমূহ ইনস্টল করুন (ডকুমেন্টেশন টুলিং এর জন্য)
npm install

# পৃথক পাঠের টাইপস্ক্রিপ্ট উদাহরণগুলির জন্য, নির্দিষ্ট পাঠে যান:
cd 06-text-generation-apps/typescript/recipe-app
npm install
```

### Dev Container সেটআপ (সুপারিশকৃত)

এই রেপোজিটরির একটি `.devcontainer` কনফিগারেশন রয়েছে যা GitHub Codespaces বা VS Code Dev Containers এর জন্য:

১. GitHub Codespaces বা VS Code-এ Dev Containers এক্সটেনশনসহ রেপোজিটরি খুলুন
২. Dev Container স্বয়ংক্রিয়ভাবে করবে:
   - `requirements.txt` থেকে Python ডিপেনডেন্সি ইনস্টল করবে
   - পোস্ট-ক্রিয়েট স্ক্রিপ্ট চালাবে (`.devcontainer/post-create.sh`)
   - Jupyter kernel সেটআপ করবে

## উন্নয়ন ওয়ার্কফ্লো

### পরিবেশ চলকসমূহ

API ব্যবহারের জন্য সমস্ত পাঠ পরিবেশ চলক ব্যবহার করে যা `.env` ফাইলে সংজ্ঞায়িত:

- `OPENAI_API_KEY` - OpenAI API জন্য
- `AZURE_OPENAI_API_KEY` - Microsoft Foundry-তে Azure OpenAI এর জন্য (Azure OpenAI সার্ভিস এখন Microsoft Foundry এর অংশ: 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`**, যা একটি বর্তমান, নিষিদ্ধ নয় এমন **রিজনিং** মডেল। ২০২৬ থেকে পুরনো তাপমাত্রা-সমর্থনকারী "মিনি" মডেলগুলো (`gpt-4o-mini`, `gpt-4.1-mini`) *ডিপ্রিকেটিং* হচ্ছে, তাই পাঠ্যক্রম GPT-5 পরিবারে স্ট্যান্ডার্ডাইজড।
- **রিজনিং মডেলগুলো `temperature` এবং `top_p` প্রত্যাখ্যান করে**, এবং `max_output_tokens` (Responses API) / `max_completion_tokens` (চ্যাট কমপ্লিশন) ব্যবহার করে `max_tokens` এর পরিবর্তে। কেবল `gpt-5-mini` কল করা স্যাম্পলে `temperature`/`top_p`/`max_tokens` যোগ করবেন না।
- **`temperature` প্রদর্শনের জন্য**, স্যাম্পলগুলো Microsoft Foundry Models এন্ডপয়েন্ট (`AZURE_INFERENCE_CHAT_MODEL`) এর মাধ্যমে **Llama** মডেল (`Llama-3.3-70B-Instruct`) ব্যবহার করে। রিজনিং মডেল নিয়ন্ত্রণ করুন প্রম্পট ইঞ্জিনিয়ারিং + রিজনিং কন্ট্রোল দিয়ে, স্যাম্পলিং নিয়ন্ত্রণের বদলে।
- **ফাইন-টিউনিং (পাঠ ১৮)** তে `gpt-4.1-mini` রাখা হয়েছে: GPT-5 শুধুমাত্র রেইনফোর্সমেন্ট ফাইন-টিউনিং (RFT) সমর্থন করে, নির্দেশিক ফাইন-টিউনিং (SFT) নয় যা সেখানে দেখানো হয়েছে।
- পাঠ ২০ (Mistral) এবং ২১ (Meta) তে `temperature`/`max_tokens` রাখা হয়েছে কারণ তারা Mistral/Llama মডেল লক্ষ্য করে, যা সেগুলোকে সমর্থন করে।

### Python উদাহরণ চালানো

```bash
# পাঠের ডিরেক্টরিতে যান
cd 06-text-generation-apps/python

# একটি পাইথন স্ক্রিপ্ট চালান
python aoai-app.py
```

### TypeScript উদাহরণ চালানো

```bash
# টাইপস্ক্রিপ্ট অ্যাপ ডিরেক্টরিতে নেভিগেট করুন
cd 06-text-generation-apps/typescript/recipe-app

# টাইপস্ক্রিপ্ট কোড তৈরি করুন
npm run build

# অ্যাপ্লিকেশন চালান
npm start
```

### Jupyter Notebooks চালানো

```bash
# রেপোজিটরির মূল ফোল্ডারে জুপিটার শুরু করুন
jupyter notebook

# অথবা জুপিটার এক্সটেনশন সহ ভিএস কোড ব্যবহার করুন
```

### বিভিন্ন ধরনের পাঠ নিয়ে কাজ করা

- **"শিখুন" পাঠ**: README.md ডকুমেন্টেশন এবং ধারণার উপর ফোকাস
- **"তৈরি করুন" পাঠ**: Python এবং TypeScript এ কাজ করা কোড উদাহরণ অন্তর্ভুক্ত
- প্রতিটি পাঠের একটি README.md থাকে তত্ত্ব, কোড ওয়াকথ্রু এবং ভিডিও কন্টেন্ট লিঙ্কসহ

## কোড স্টাইল গাইডলাইনসমূহ

### Python

- পরিবেশ চলক ব্যবস্থাপনার জন্য `python-dotenv` ব্যবহার করুন
- API ইন্টারঅ্যাকশনের জন্য `openai` লাইব্রেরি ইমপোর্ট করুন
- লিন্টিং এর জন্য `pylint` ব্যবহার করুন (কিছু উদাহরণে সরলতার জন্য `# pylint: disable=all` ব্যবহার আছে)
- PEP 8 নামকরণ বিধি অনুসরণ করুন
- API ক্রেডেনশিয়াল `.env` ফাইলে সংরক্ষণ করুন, কোডে নয়

### TypeScript

- পরিবেশ চলকের জন্য `dotenv` প্যাকেজ ব্যবহার করুন
- প্রতিটি অ্যাপের জন্য `tsconfig.json` এ TypeScript কনফিগারেশন
- 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 যুগ থেকে রাখা লিগ্যাসি প্রিফিক্স)

## ডকুমেন্টেশন গাইডলাইনসমূহ

### মার্কডাউন স্টাইল

- সমস্ত URL অবশ্যই `[text](../../url)` ফরম্যাটে এবং অতিরিক্ত স্পেস বিহীন হতে হবে
- সম্পর্কিত লিঙ্ক অবশ্যই `./` অথবা `../` দিয়ে শুরু হবে
- Microsoft ডোমেইনের সকল লিঙ্কে ট্র্যাকিং আইডি থাকতে হবে: `?WT.mc_id=academic-105485-koreyst`
- URL এ দেশের নির্দিষ্ট লোকেল এড়ান (যেমন `/en-us/`)
- ছবি `./images` ফোল্ডারে সংরক্ষণ করবেন বর্ণনামূলক নামে
- ফাইল নাম ইংরেজি অক্ষর, সংখ্যা, এবং ড্যাশ ব্যবহার করুন

### অনুবাদ সমর্থন

- রেপোজিটরিটি স্বয়ংক্রিয় GitHub Actions মাধ্যমে ৪০+ ভাষা সমর্থন করে
- অনুবাদসমূহ `translations/` ডিরেক্টরিতে সংরক্ষিত
- আংশিক অনুবাদ সাবমিট করবেন না
- মেশিন অনুবাদ গ্রহণযোগ্য নয়
- অনূদিত ছবি `translated_images/` ডিরেক্টরিতে সংরক্ষিত

## পরীক্ষা এবং বৈধীকরণ

### সাবমিশনের আগে যাচাই

এই রেপোজিটরিতে GitHub Actions ব্যবহার করে বৈধীকরণ। PR জমা দেওয়ার আগে:

১. **মার্কডাউন লিঙ্ক চেক করুন**:
   ```bash
   # validate-markdown.yml ওয়ার্কফ্লোটি যাচাই করে:
   # - ভগ্ন আপেক্ষিক পথ
   # - পথগুলিতে অনুপস্থিত ট্র্যাকিং আইডি
   # - URL-এ অনুপস্থিত ট্র্যাকিং আইডি
   # - দেশের লোকেল সহ URL
   # - ভগ্ন বহির্গত URL
   ```

২. **ম্যানুয়াল টেস্টিং**:
   - Python উদাহরণ পরীক্ষা করুন: venv সক্রিয় করে স্ক্রিপ্ট চালান
   - TypeScript উদাহরণ পরীক্ষা করুন: `npm install`, `npm run build`, `npm start`
   - পরিবেশ চলক সঠিকভাবে কনফিগার করা আছে কিনা যাচাই করুন
   - API কী কোড উদাহরণের সাথে কাজ করছে কিনা পরীক্ষা করুন

৩. **কোড উদাহরণ**:
   - নিশ্চিত করুন সব কোড ত্রুটির মুক্তে চলছে
   - যেখানে প্রযোজ্য, Azure OpenAI এবং OpenAI API উভয়ের সাথে পরীক্ষা করুন
   - যেখানে সমর্থিত, Microsoft Foundry Models এর সাথে উদাহরণগুলো কাজ করে কিনা যাচাই করুন

### কোনো স্বয়ংক্রিয় পরীক্ষা নেই

এটি একটি শিক্ষামূলক রেপোজিটরি, টিউটোরিয়াল এবং উদাহরণে কেন্দ্রীভূত। এখানে ইউনিট টেস্ট বা ইন্টিগ্রেশন টেস্ট চালানোর কোন ব্যবস্থা নেই। বৈধীকরণ মূলত:
- কোড উদাহরণের ম্যানুয়াল পরীক্ষা
- মার্কডাউন যাচাইয়ের জন্য GitHub Actions
- শিক্ষামূলক বিষয়বস্তুর জন্য কমিউনিটি পর্যালোচনা

## পুল রিকোয়েস্ট গাইডলাইনসমূহ

### জমা দেওয়ার আগে

১. Python এবং TypeScript উভয় ক্ষেত্রে কোড পরিবর্তন পরীক্ষা করুন যেখানে প্রযোজ্য
২. মার্কডাউন যাচাই চালান (অটোমেটিকালি PR এ ট্রিগার)
৩. সব Microsoft URL এ ট্র্যাকিং আইডি আছে কিনা নিশ্চিত করুন
৪. সম্পর্কিত লিঙ্কগুলো বৈধ কিনা যাচাই করুন
৫. ছবি সঠিকভাবে রেফারেন্স আছে কিনা নিশ্চিত করুন

### পিআর শিরোনাম ফরম্যাট

- বর্ণনামূলক শিরোনাম ব্যবহার করুন: `[Lesson 06] Fix Python example typo` অথবা `Update README for lesson 08`
- যেখানে প্রযোজ্য ইস্যু নম্বর উল্লেখ করুন: `Fixes #123`

### পিআর বর্ণনা

- কী পরিবর্তন হয়েছে এবং কেন তা ব্যাখ্যা করুন
- সংশ্লিষ্ট ইস্যুগুলোর লিঙ্ক দিন
- কোড পরিবর্তনের ক্ষেত্রে কোন উদাহরণ পরীক্ষা করা হয়েছে তা উল্লেখ করুন
- অনুবাদ পিআরের জন্য, সম্পূর্ণ অনুবাদের জন্য সব ফাইল অন্তর্ভুক্ত করুন

### অবদান শর্তাবলী

- Microsoft CLA স্বাক্ষর করুন (প্রথম PR এ স্বয়ংক্রিয়)
- পরিবর্তনের পূর্বে রেপোজিটরিটি আপনার অ্যাকাউন্টে Fork করুন
- একটি লজিক্যাল পরিবর্তনের জন্য একটি PR করুন (অপ্রাসঙ্গিক সংশোধন একত্র করবেন না)
- সম্ভব হলে পিআর ছোট এবং ফোকাসড রাখুন

## সাধারণ ওয়ার্কফ্লো

### নতুন কোড উদাহরণ যোগ করা

১. সংশ্লিষ্ট পাঠ ডিরেক্টরিতে যান
২. `python/` বা `typescript/` সাবডিরেক্টরিতে উদাহরণ তৈরি করুন
৩. নামকরণের নিয়ম অনুসরণ করুন: `{provider}-{example-name}.{py|ts|js}`
৪. বাস্তব API ক্রেডেনশিয়াল দিয়ে পরীক্ষা করুন
৫. পাঠের README-তে নতুন পরিবেশ চলকসমূহ ডকুমেন্ট করুন

### ডকুমেন্টেশন আপডেট করা

১. পাঠ ডিরেক্টরির README.md সম্পাদনা করুন
২. মার্কডাউন নির্দেশিকা অনুসরণ করুন (ট্র্যাকিং আইডি, সম্পর্কিত লিঙ্ক)
৩. অনুবাদ আপডেট GitHub Actions দ্বারা হ্যান্ডেল হয় (ম্যানুয়ালি সম্পাদনা করবেন না)
৪. সব লিঙ্ক বৈধ কিনা পরীক্ষা করুন

### Dev Containers নিয়ে কাজ করা

১. রেপোজিটরিতে `.devcontainer/devcontainer.json` অন্তর্ভুক্ত
২. পোস্ট-ক্রিয়েট স্ক্রিপ্ট স্বয়ংক্রিয়ভাবে Python ডিপেনডেন্সি ইনস্টল করে
৩. Python এবং Jupyter এক্সটেনশন প্রি-কনফিগার্ড
৪. এনভায়রনমেন্ট `mcr.microsoft.com/devcontainers/universal:2.11.2` ভিত্তিক

## ডিপ্লয়মেন্ট এবং পাবলিশিং

এটি একটি শিক্ষণীয় রেপোজিটরি - এখানে কোনো ডিপ্লয়মেন্ট প্রক্রিয়া নেই। পাঠ্যক্রম নিম্নরূপ ব্যবহৃত হয়:

১. **GitHub রেপোজিটরি**: সরাসরি কোড এবং ডকুমেন্টেশন অ্যাক্সেস
২. **GitHub Codespaces**: প্রাক-কনফিগার্ড সেটআপসহ তাত্ক্ষণিক ডেভ পরিবেশ
৩. **Microsoft Learn**: বিষয়বস্তু অফিসিয়াল লার্নিং প্ল্যাটফর্মে শেয়ার হতে পারে
৪. **docsify**: Markdown থেকে নির্মিত ডকুমেন্টেশন সাইট (দেখুন `docsifytopdf.js` এবং `package.json`)

### ডকুমেন্টেশন সাইট নির্মাণ

```bash
# প্রয়োজনে ডকুমেন্টেশন থেকে PDF তৈরি করুন
npm run convert
```

## সমস্যা নিরসন

### সাধারণ সমস্যা

**Python ইমপোর্ট ত্রুটি**:
- নিশ্চিত করুন ভার্চুয়াল এনভায়রনমেন্ট সক্রিয় আছে
- `pip install -r requirements.txt` চালান
- Python সংস্করণ ৩.৯+ চেক করুন

**TypeScript বিল্ড ত্রুটি**:
- নির্দিষ্ট অ্যাপ ডিরেক্টরিতে `npm install` চালান
- Node.js সংস্করণ সামঞ্জস্যপূর্ণ কিনা চেক করুন
- `node_modules` ফোল্ডার পরিষ্কার করে প্রয়োজনে পুনঃইনস্টল করুন

**API অথেনটিকেশন ত্রুটি**:
- যাচাই করুন `.env` ফাইল আছে এবং সঠিক মান পূর্ণ হয়েছে
- API কী যথাযথ ও মেয়াদ উত্তীর্ণ নয় নিশ্চিত করুন
- আপনার অঞ্চলের জন্য এন্ডপয়েন্ট URL সঠিক কিনা নিশ্চিত করুন

**হ্রাসপ্রাপ্ত পরিবেশ চলকসমূহ**:
- `.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 -->