# فصل ۷ — اولین تماس با AI: الگوی پل

<div dir="rtl">

# فصل ۷ — اولین تماس با AI: الگوی پل

## در این فصل چه می‌سازی

امروز روزِ برداشت است: تا آخرِ این فصل، برنامه‌ای که **خودت نوشته‌ای** به یک هوش مصنوعی پیام می‌فرستد و جوابش را می‌گیرد — نه در سایتِ کسی، نه در اپِ کسی، در کدِ خودت. یک تصمیمِ مهندسیِ کوچک اول کار: امروز ESP32 استراحت می‌کند! به این می‌گویند **الگوی پل**: برای رسیدن به قلهٔ تازه، اول از راهِ هموارتر برو. کامپیوترت هزاران برابرِ برد حافظه دارد و خطاهایش راحت‌تر دیده می‌شوند؛ پس اول از کامپیوتر با AI حرف می‌زنیم تا الگو دستمان بیاید، و فصل ۹ همین کار را مستقیم از خودِ برد می‌کنیم.

![الگوی پل برای اتصال به AI: سه جزیره در یک ردیف — جزیرهٔ چپ یک بردِ کوچکِ ESP32 با آیکونِ خواب و تابلوی «Session 9»، جزیرهٔ وسط یک لپ‌تاپِ روشن و فعال، جزیرهٔ راست یک ابرِ دیتاسنتر با نشانِ درخشانِ AI؛ یک پلِ محکم و روشن، جزیرهٔ لپ‌تاپ را به ابرِ AI وصل کرده و یک بستهٔ داده رویش در حرکت است؛ پلِ کم‌رنگِ آینده هم از جزیرهٔ ESP32 مستقیم به ابر کشیده شده](/lesson-assets/t4-s07-first-ai-call/prompt/01-image-bridge-pattern.png)

آخر این فصل می‌توانی:

- فرقِ MicroPython روی برد و Python استاندارد روی کامپیوتر را بگویی و Python را روی کامپیوتر نصب و در ترمینال اجرا کنی.
- با `pip` کتابخانهٔ `requests` را نصب کنی.
- بگویی prompt چیست و درخواستِ POST چه فرقی با GET دارد.
- با الگوی عمومیِ «POST + JSON + کلیدِ API» از کدِ خودت به Gemini پیام بفرستی و جواب را از دلِ JSON تودرتو بیرون بکشی.
- با `input()` یک چتِ ساده در ترمینال بسازی و خطاهای ۴۰۳ و ۴۲۹ و KeyError را بشناسی و رفع کنی.

## قبل از شروع: چک‌لیست پیش‌نیاز

قبل از ادامه این‌ها را چک کن — اگر یکی‌شان لنگ می‌زند، اول برگرد همان فصل:

- **از فصل ۶:** دیکشنریِ کامل و ساختارِ تودرتو، `json.dumps` و `json.loads`، مفهومِ API key و rate limit، فایلِ `secrets.py` — همه امروز به میدان می‌آیند.
- **از فصل ۲:** HTTP، request و response، status code، تشبیهِ رستوران — امروز سفارشِ نوعِ جدیدی می‌دهیم.
- **از ترم ۳، فصل ۸:** حلقهٔ `while` با متغیرِ پرچم — قلبِ چتِ ترمینالیِ امروز.
- **از ترم ۲، فصل ۶:** نصبِ کتابخانه و `try/except` — امروز همان کارها را با ابزارِ جدید می‌کنیم.
- **از ترم ۱، فصل ۴:** REPL و Thonny — ترمینالِ امروز را با مقایسه با REPL یاد می‌گیریم.

لوازم این فصل:

| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| کامپیوتر (ویندوز/مک/لینوکس) با اینترنت | ۱ | همان کامپیوترِ Thonny کافی است |
| کلیدِ رایگانِ Gemini API (ساختهٔ والدین) | ۱ | راهنمای قدم‌به‌قدمِ والدین در بخشِ ۳ همین فصل |
| ESP32 | ۰ | امروز برد استراحت می‌کند — فصل ۹ برمی‌گردد! |

> 💡 **نکته:** این فصل روی کامپیوتر اجرا می‌شود، نه برد — پس شبیه‌سازِ امروز تعطیل است. اگر نمی‌توانی Python نصب کنی (مثلاً کامپیوترِ مدرسه است)، Thonny خودش یک Python کامل دارد: از گوشهٔ پایین-راست، به‌جای MicroPython گزینهٔ Local Python 3 را بزن و `requests` را از همان Manage packages نصب کن.

## ۱. دو پایتون: نسخهٔ جیبی و نسخهٔ کامل

یک رازِ کوچک: چیزی که سه ترم است می‌نویسی، «MicroPython» است — **نسخهٔ جیبیِ** Python، مثلِ نسخهٔ Liteِ یک بازیِ موبایل: همان بازی، سبک‌شده برای دستگاهِ کوچک. Python اصلی روی کامپیوترها زندگی می‌کند، و خبرِ عالی: زبانش **همان زبان است** — متغیر، شرط، حلقه، تابع، دیکشنری، همه را بلدی! فرق‌ها کوچک‌اند: نسخهٔ کامل کتابخانه‌های خیلی بیشتر و حافظه‌ای تمام‌نشدنی دارد، و در عوض `machine` و `Pin` ندارد — کامپیوترِ تو پایهٔ GPIO ندارد که LED به آن ببندی!

![دو مارِ پایتونِ کارتونی به‌عنوانِ نمادِ نرم‌افزار: سمت چپ یک پایتونِ بزرگ و سیر که دورِ یک کامپیوترِ رومیزی پیچیده و کلی آیکونِ کتابخانه و نشانِ requests دارد، با برچسبِ Python؛ سمت راست یک پایتونِ کوچکِ جیبی که روی یک تراشهٔ ESP32 لم داده و جعبه‌ابزارِ کوچکی با نشانِ machine.Pin دارد، با برچسبِ MicroPython؛ بینشان یک علامتِ مساوی با قلب که نشان می‌دهد هر دو یک زبان حرف می‌زنند](/lesson-assets/t4-s07-first-ai-call/prompt/02-image-two-pythons.png)

نصبش کنیم. به سایتِ رسمیِ Python برو (`python.org`) و نصب‌کننده را دانلود کن. موقعِ نصب یک لحظهٔ حیاتی هست که نصفِ مشکلاتِ دنیا را می‌سازد: در اولین صفحه، تیکِ **Add to PATH** را حتماً بزن — یعنی «اسمِ python را به سیستم‌عامل معرفی کن». بدونِ این تیک، بعداً سیستم می‌گوید «python؟ نمی‌شناسم!».

حالا با ابزارِ محبوبِ برنامه‌نویس‌ها آشنا شو: **ترمینال** — پنجرهٔ سیاهی که فقط متن دارد. ترسناک نیست؛ دو ترم است با پسرعمویش REPL زندگی می‌کنی! همان‌طور که REPL دستور می‌گرفت و جوابِ Python می‌داد، ترمینال دستور می‌گیرد و جوابِ **سیستم‌عامل** را می‌دهد. در ویندوز اسمش PowerShell است، در مک و لینوکس Terminal. بازش کن و اولین دستور را بزن:

</div>

```text
> python --version
Python 3.12.4
```

<div dir="rtl">

اگر شمارهٔ نسخه آمد (شمارهٔ دقیق مهم نیست — مالِ تو احتمالاً جدیدتر است)، Python کامل روی کامپیوترت زنده است. تبریک — حالا دو پایتون داری!

✅ **چک کن:** باید در جوابِ `python --version` یک شمارهٔ نسخه ببینی (مثلِ `Python 3.12.4`)، نه پیامِ خطا. اگر شماره آمد، Python کامل نصب و به سیستم معرفی شده.

## چالش: machine.Pin روی کامپیوتر هست؟

`machine.Pin` در Python کامپیوتر هست یا نه؟ چرا؟

---

**جواب:** نه! `machine.Pin` برای کنترلِ پایه‌های سخت‌افزار است و کامپیوترِ تو اصلاً پایهٔ GPIO ندارد که LED یا سنسور به آن ببندی. این ابزار مالِ دنیای MicroPython روی برد است. در عوض، Python کامل هزاران کتابخانهٔ دیگر دارد که برد ندارد — هر کدام برای دنیای خودش.

## ۲. pip: فروشگاهِ کتابخانه‌ها، این بار تایپی

برای حرف زدن با اینترنت، Python کامل هم کتابخانه می‌خواهد. آنجا `urequests` داشتیم؛ اینجا برادرِ بزرگش: `requests` — بدونِ u! همان خانواده، فقط کامل‌تر. ترم ۲ کتابخانه‌ها را از Manage packages نصب می‌کردی؛ روی کامپیوتر همان فروشگاه را تایپی داریم: **pip**.

اول بگذار یک اشتباهِ کلاسیک را عمداً بکنیم که تو هیچ‌وقت نکنی. در ترمینال تایپ کن `python` و Enter — سه فلشِ آشنا می‌آید: `>>>` — این همان REPL است، این بار REPL کامپیوتر! و حالا همین‌جا بنویس:

</div>

```text
>>> pip install requests
  File "<stdin>", line 1
    pip install requests
        ^^^^^^^
SyntaxError: invalid syntax
```

<div dir="rtl">

`SyntaxError`! چرا؟ چون `pip install requests` جملهٔ زبانِ Python نیست — دستورِ **ترمینال** است و جای اشتباهی تایپ شد. این گیج‌کننده‌ترین لحظهٔ شروعِ کار است، پس قاعده‌اش را قاب کن: `>>>` یعنی «داخلِ Python هستی»، بدونِ `>>>` یعنی «در ترمینال هستی». با `exit()` از Python بیرون بیا و حالا در خودِ ترمینال:

</div>

```text
> pip install requests
Collecting requests
  Downloading requests-2.32.3-py3-none-any.whl
Successfully installed requests-2.32.3 ...
```

<div dir="rtl">

پیامِ Successfully یعنی نصب شد. شماره‌های وسطِ آن خط‌ها (نسخهٔ بسته) مالِ همان روزِ ضبط است و مالِ تو تازه‌تر خواهد بود — به عددها نگاه نکن، به کلمهٔ **Successfully** نگاه کن. امتحانِ نهایی مثلِ همیشه: `python` را باز کن، `import requests` — سکوت. سکوت یعنی پیروزی!

✅ **چک کن:** بعد از `import requests` باید بی هیچ پیامِ خطایی به خطِ `>>>` برگردی. آن سکوت یعنی کتابخانه نصب و آمادهٔ استفاده است.

> 🔧 **اگر کار نکرد:** پیامِ `'python' is not recognized...` گرفتی؟ تیکِ Add to PATH موقعِ نصب زده نشده — نصب را دوباره اجرا کن و تیک را بزن (یا در ویندوز به‌جای `python` بنویس `py`). و اگر بعدِ نصب هم `ModuleNotFoundError: No module named 'requests'` گرفتی، شاید چند Python روی سیستم است؛ به‌جای `pip install requests` بنویس `python -m pip install requests`.

## چالش: pip را کجا تایپ کنی؟

`pip install` را باید وقتی `>>>` می‌بینی تایپ کنی یا وقتی نمی‌بینی؟

---

**جواب:** وقتی `>>>` را **نمی‌بینی**! `>>>` یعنی داخلِ Python هستی و pip آنجا جملهٔ نامفهومی است (SyntaxError). pip دستورِ ترمینال است، پس باید در خودِ ترمینال — جایی که `>>>` نیست — تایپ شود.

## ۳. کلید در خانهٔ امن + prompt چیست

حالا مهم‌ترین قطعه: کلید. کلیدِ رایگانِ Gemini را پدر یا مادرت با حسابِ Google خودش می‌سازد، چون شرایطِ این سرویس در زمانِ نوشتنِ این فصل فقط برای بزرگسالان است. این راهنما برای اوست:

1. در مرورگر به `aistudio.google.com` بروید و با حسابِ Google بزرگسال وارد شوید.
2. شرایطِ استفاده را بخوانید و اگر قبول دارید بپذیرید.
3. بخشِ مربوط به کلیدها را پیدا کنید و یک کلیدِ تازه بسازید. یک رشتهٔ طولانی از حرف و عدد می‌گیرید.
4. کلید را کامل کپی کنید و کنارِ فرزندتان در فایلِ `secrets.py` پایین بگذارید. جای دیگری نگهش ندارید.

> 💡 **نکته:** صفحه‌های Google هر چند وقت یک بار عوض می‌شوند. اگر چیدمان فرق داشت، دنبالِ همین چهار کار بگرد: ورود، پذیرشِ شرایط، ساختِ کلید، کپی‌کردن. این سرویس هم همه‌جا در دسترس نیست و شرایطش ممکن است عوض شود. در ردهٔ رایگان ممکن است متنِ پیام‌ها برای بهترکردنِ مدل استفاده شود، و این یک دلیلِ دیگر است که چیزِ خصوصی نفرستی.

حالا کلید داری، و فصل قبل گفتیم: کلید **مثلِ رمزِ عبور** است، پس همان‌جایی می‌رود که رمزها می‌روند: `secrets.py`. روی کامپیوتر یک پوشه برای پروژه بساز — مثلاً `airo-ai` روی دسکتاپ — و الگوی آشنای فصل ۶ را داخلش بساز، این بار با ساکنِ جدید:

</div>

```python
# secrets.py - hame-ye ramz-haye project inja hastand
# IN FILE RA BA HICHKAS SHARE NAKON! na git, na Wokwi-e umumi, na screenshot!

GEMINI_API_KEY = "kelid-e-vagheiy-ra-inja-bogzar"
```

<div dir="rtl">

اگر روزی از صفحه‌ات فیلم گرفتی یا عکس فرستادی، رویِ خطِ کلید را تار کن. کلید لو رفت؟ مثلِ رمزِ عبور: در همان سایت باطلش کن و کلیدِ نو بساز.

و حالا مفهومِ ستارهٔ امشب: **prompt** — بخوان «پرامپت». پرامپت یعنی متنی که به AI می‌فرستی: سؤالت، درخواستت، توضیحِ کاری که می‌خواهی. همین! ولی یک قانونِ طلایی دارد: **هرچه دقیق‌تر بگویی چه می‌خواهی، بهتر می‌گیری.** مثلِ سفارش به آشپزی که هر غذایی بلد است: «یک چیزی بده» یک چیزی می‌دهد؛ «پاستای بدونِ فلفل، سسِ کم» دقیقاً همان می‌شود.

> 💡 **نکته:** پرامپت را در کد به انگلیسیِ ساده می‌نویسیم تا کد تمیز و LTR بماند — ولی داخلش می‌گوییم «به فارسی جواب بده». مدل‌ها فارسی را خوب می‌فهمند و می‌نویسند؛ هر جا خواستی، خودِ پرامپت را هم فارسی بده.

## چالش: کدام پرامپت بهتر است؟

کدام پرامپت جوابِ بهتری می‌گیرد — «دربارهٔ ربات بگو» یا «سه کاربردِ ربات در بیمارستان را برای یک نوجوان در سه جمله توضیح بده»؟ چرا؟

---

**جواب:** دومی. چون دقیق است: موضوع (کاربردِ ربات در بیمارستان)، تعداد (سه)، مخاطب (نوجوان) و قالب (سه جمله) را مشخص کرده. AI جای خالی برای حدس‌زدن ندارد، پس جوابش هدفمند و مفید می‌شود. «دربارهٔ ربات بگو» آن‌قدر باز است که هزار جوابِ متفاوت دارد و معلوم نیست کدامش را می‌خواهی.

## ۴. اولین تماس: سفارشی از نوعِ جدید

برویم سفارش بدهیم. ولی صبر کن: سفارش‌های ترمِ ما تا امروز همه **GET** بودند: «فقط بده ببینم». الان فرق دارد — خودمان چیزی برای فرستادن داریم: پرامپت! اینجا نوعِ دومِ سفارش وارد می‌شود: **POST**. اگر GET یعنی از پیشخوان بپرسی «منو چی دارید؟»، POST یعنی بسته‌ای بدهی دستِ رستوران: «این را بگیر، طبقِ این برایم بساز.» داده می‌رود **و** جواب برمی‌گردد.

بستهٔ POST ما سه قسمت دارد — این ساختار را قاب کن، چون الگوی همهٔ سرویس‌های AI دنیاست:

1. **آدرس (URL):** کجا بفرستیم — آدرسِ سرویسِ Gemini و اسمِ مدلش (در کدِ پایین آمده است).
2. **هدرها (headers):** برچسب‌های روی بسته — یکی می‌گوید محتوا JSON است، یکی کلیدِ توست.
3. **بدنه (body):** خودِ نامه — پرامپت، در قالبی که Gemini می‌خواهد (دیکشنریِ تودرتو!).

آدرس را از خطِ `URL` کدِ پایین بردار. هدرها دو تا لازم داریم: یکی می‌گوید «محتوای بسته JSON است» و دیگری **کلید** توست، چسبیده روی بسته، که سرویس بداند این سفارش مالِ کیست. و بدنه یک **دیکشنریِ تودرتو** است — داخلش لیست، داخلِ لیست دیکشنری — دقیقاً همان هیولای دوست‌داشتنی که فصل ۶ رامش کردی. برای متن‌کردنش هم `json.dumps` را داریم؛ قولش را داده بودم که «برای فرستادن» به کار می‌آید.

![آناتومیِ یک درخواستِ POST به شکلِ یک بستهٔ پستی: برچسبِ بزرگِ POST روی جعبه؛ سه فلشِ توضیح: (۱) برچسبِ آدرس با نامِ URL روی خطِ نشانی، (۲) دو استیکرِ HEADERS روی جعبه — یکی «Content-Type: JSON» و دیگری آیکونِ کلیدِ طلاییِ API KEY، (۳) دربِ بازِ جعبه که نامه‌ای با ساختارِ آکولادهای تودرتوی JSON با برچسبِ BODY نشان می‌دهد؛ گوشهٔ تصویر ابری با نشانِ AI به‌عنوانِ مقصد](/lesson-assets/t4-s07-first-ai-call/prompt/03-image-post-package-anatomy.png)

فایلِ `01_first_ai_call.py` را در همان پوشه بساز. import ها، آدرس، هدرها با کلید از `secrets`، پرامپت، بدنهٔ تودرتو، و شلیک با `requests.post`. کدِ کامل در `01_first_ai_call.py`:

</div>

```python
# Term 4 - Session 07 - avalin tamas ba AI (roye COMPUTER, na ESP32!)
# ejra dar terminal:  python 01_first_ai_call.py
# pish-niaz: pip install requests  +  file-e secrets.py kenar-e hamin file
import requests
import json
import secrets

# address + esm-e model: gahi avaz mishavand (404 = esm-e model avaz shode)
URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent"

headers = {
    "Content-Type": "application/json",        # mohtavaye baste JSON ast
    "x-goog-api-key": secrets.GEMINI_API_KEY,  # kelid az khane-ye amn - hargez mostaghim nanevis!
}

# prompt = sefaresh-e daghigh-e to be AI
prompt = "You are a friendly robot. Say hello to a teenage robotics student in one short Persian sentence."

# body = name-ye ma dar ghaleb-e Gemini: dictionary-e too dar too (jalase 6!)
body = {
    "contents": [
        {"parts": [{"text": prompt}]}
    ]
}

print("dar hale ferestadan-e sefaresh (POST)...")
r = requests.post(URL, headers=headers, data=json.dumps(body))
print(f"status code: {r.status_code}")
print("---- matn-e kham-e pasokh ----")
print(r.text)
```

<div dir="rtl">

به دو خطِ `headers` خوب دقت کن: کلیدِ تو در سربرگی به اسمِ `x-goog-api-key` می‌رود که سرویسِ Gemini با آن تو را می‌شناسد — نه در آدرس، نه در بدنه، فقط همین سربرگ. حالا در ترمینال اجرا کن:

</div>

```text
> python 01_first_ai_call.py
dar hale ferestadan-e sefaresh (POST)...
status code: 200
---- matn-e kham-e pasokh ----
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "سلام! من یک ربات مهربانم و از آشنایی با تو خیلی خوشحالم!"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  ...
```

<div dir="rtl">

یک لحظه مکث کن. status code: **۲۰۰**. و آن وسط، بینِ آکولادها، یک جملهٔ فارسی که چند لحظه پیش **هیچ‌جای دنیا وجود نداشت**. یک هوش مصنوعی آن را همین الان، در جوابِ کدِ تو، نوشت. این اولین مکالمهٔ کدِ تو با AI بود — تاریخ بزن!

✅ **چک کن:** باید `status code: 200` را ببینی و پایینش، لای آکولادهای JSON، یک جملهٔ فارسیِ تازه که AI همین حالا برایت نوشت. اگر ۲۰۰ نیامد، بلوکِ زیر را بخوان.

> 🔧 **اگر کار نکرد:** به‌جای ۲۰۰ عددِ دیگری دیدی؟ دو بلای رایج را بشناس. **۴۰۳** (یا PERMISSION_DENIED) یعنی «تو را نمی‌شناسم — کلید نرسیده»: مستقیم برو سراغِ کلید — هست؟ درست کپی شده؟ اسمِ هدرش (`x-goog-api-key`) درست است؟ (کلیدِ غلط ممکن است ۴۰۰ با پیامِ «API key not valid» بدهد؛ معنی‌اش یکی است: مشکل از کلید.) **۴۲۹** (RESOURCE_EXHAUSTED) یعنی «سهمیه‌ات فعلاً تمام — نفس بگیر»: کلیدت خراب نشده، کمی صبر کنی برمی‌گردد. همان قانونِ بوفهٔ فصل ۶: حلقه‌های تند و بی‌وقفه ننویس؛ فقط وقتی لازم است بپرس — هم به‌خاطرِ سرویس، هم به‌خاطرِ برقی که در دیتاسنترها می‌سوزد.

## ۵. بیرون کشیدن جواب از JSON تودرتو

مهندس با «یک جایی آن وسط» راضی نمی‌شود — باید جواب را تمیز بیرون بکشیم. قیافهٔ پاسخ را نگاه کن: `candidates` یک لیست است (سرویس می‌تواند چند جوابِ پیشنهادی بدهد، معمولاً یکی)، عضوِ اولش `[0]`، داخلش `content`، داخلِ آن `parts` که باز لیست است، عضوِ اولش، و بالاخره `text`. بگذار اول مثلِ کارآگاهِ فصل ۶ عمداً غلط برویم که راهش یادمان بماند — عجله کن و بنویس `data["text"]`:

</div>

```text
Traceback (most recent call last):
  File "C:\Users\airo\Desktop\airo-ai\02_parse_answer.py", line 27, in <module>
    answer = data["text"]
KeyError: 'text'
```

<div dir="rtl">

`KeyError: 'text'` — آشنای قدیمی! کشوی `text` در طبقهٔ اولِ قفسه نیست؛ پنج طبقه پایین‌تر است. قانونِ کارآگاه: اول نقشه را چاپ کن، بعد مسیر را طبقه‌به‌طبقه بنویس.

![مسیرِ گنج در JSON تودرتو: یک راهِ نقطه‌چین که از پنج صندوقچهٔ تودرتو رد می‌شود، هر صندوق در صندوقِ بعدی باز می‌شود، با پرچم‌های ترتیبیِ candidates و [0] و content و parts و [0] و صندوقِ درخشانِ پایانیِ text که یک جواهرِ حباب‌گفتار دارد؛ پایینِ تصویر مسیرِ کامل به شکلِ چیپ: data > candidates > 0 > content > parts > 0 > text](prompt/05-image-nested-answer-path.png)

مسیرِ درست را طبقه‌به‌طبقه بنویس. کدِ کامل در `02_parse_answer.py`:

</div>

```python
# Term 4 - Session 07 - parse-e javab: candidates[0] -> content -> parts[0] -> text
# ejra dar terminal:  python 02_parse_answer.py
import requests
import json
import secrets

# address + esm-e model: gahi avaz mishavand (404 = esm-e model avaz shode)
URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent"

headers = {
    "Content-Type": "application/json",
    "x-goog-api-key": secrets.GEMINI_API_KEY,
}

prompt = "Suggest three fun Persian names for a small two-wheeled robot. Answer in Persian, max 3 lines."

body = {
    "contents": [
        {"parts": [{"text": prompt}]}
    ]
}

r = requests.post(URL, headers=headers, data=json.dumps(body))
data = r.json()

# ghanun-e karagah (jalase 6): aval naghshe ra chap kon, bad tabaghe be tabaghe boro
answer = data["candidates"][0]["content"]["parts"][0]["text"]
print("---- javab-e AI ----")
print(answer)
```

<div dir="rtl">

اجرا... و این بار فقط خودِ جواب، تمیز و مرتب. آن خطِ پارس — `data["candidates"][0]["content"]["parts"][0]["text"]` — را لای دفترچهٔ مهندسی‌ات بگذار؛ در سه فصلِ آینده بارها می‌نویسی‌اش. یک صداقتِ کوچک هم بدهکارم: این مسیر، مسیرِ **پاسخِ امروزِ همین سرویس** است. سرویس‌ها ساختارِ پاسخشان را عوض می‌کنند، پس اگر روزی این خط `KeyError` داد، اول نگران نشو — `print(r.text)` بزن، نقشهٔ تازه را ببین و مسیر را از رویش بنویس. مهارتِ اصلی همان «نقشه‌خوانی» است، نه حفظ‌کردنِ این یک خط.

✅ **چک کن:** این بار باید فقط خودِ جوابِ AI را ببینی — بی هیچ آکولاد و `candidates` و JSONِ خام. یعنی مسیرِ پارس را درست طبقه‌به‌طبقه رفته‌ای.

## چالش: چرا [0] بعد از candidates ولی کلید بعد از content؟

چرا بعد از `candidates` کروشه با عددِ صفر آمده ولی بعد از `content` یک کلیدِ متنی؟ کدام لیست است و کدام دیکشنری؟

---

**جواب:** `candidates` یک **لیست** است، پس عضوِ اولش را با index شماره‌دار می‌گیریم: `[0]`. ولی `content` یک **دیکشنری** است، پس داخلش را با کلیدِ اسم‌دار باز می‌کنیم: `["parts"]`. لیست کشوهای شماره‌دار دارد و دیکشنری کشوهای اسم‌دار — همان فرقِ فصل ۶. توی این پاسخ، این دو نوع پشتِ سرِ هم آمده‌اند، برای همین مسیر بین کروشهٔ عددی و کلیدِ متنی جابه‌جا می‌شود.

## ۶. پروژهٔ اصلی: چت در ترمینال

حالا که تک‌تماس را بلدیم، بیا **چتِ واقعی** بسازیم: تو تایپ کنی، AI جواب بدهد، و همین‌طور ادامه — تا خودت بگویی تمام. فقط یک قطعه کم داریم: تا حالا برنامه‌هایمان از دکمه و سنسور ورودی می‌گرفتند؛ از **آدمِ پشتِ کیبورد** چطور؟ تابعِ `input()` — قرینهٔ `print`! print می‌گوید، input گوش می‌دهد: برنامه می‌ایستد تا چیزی تایپ کنی و Enter بزنی، و آن متن را به تو می‌دهد. نکته‌ای که بعداً جانت را نجات می‌دهد: هرچه input بدهد **رشته** است — حتی اگر عدد تایپ کنی، `"42"` می‌گیری نه `42`.

طرحِ برنامه: اول تماس با AI را داخلِ یک تابعِ تمیز می‌گذاریم — `ask_ai(prompt)` — که پرامپت بگیرد و جوابِ متنی برگرداند؛ پارس را هم در `try/except KeyError` می‌گذاریم تا اگر پاسخ شکلِ عجیبی داشت، برنامه به‌جای سقوط، پیام بدهد. بعد حلقهٔ چت — و اینجا الگوی آشنای ترم ۳ برمی‌گردد: **while با متغیرِ پرچم**، همان که دنبال‌کنندهٔ خط را با آن روشن و خاموش می‌کردی. کدِ کامل در `03_terminal_chat.py`:

</div>

```python
# Term 4 - Session 07 - chat ba AI dar terminal (roye COMPUTER)
# baraye khorooj: benevis exit
# note: in chat hafeze nadarad - har soal yek tamas-e taze ast!
import requests
import json
import secrets

# address + esm-e model: gahi avaz mishavand (404 = esm-e model avaz shode)
URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent"

headers = {
    "Content-Type": "application/json",
    "x-goog-api-key": secrets.GEMINI_API_KEY,
}

def ask_ai(prompt):
    # yek tamas-e kamel: body -> POST -> parse; javab-e matni bar migardanad
    body = {
        "contents": [
            {"parts": [{"text": prompt}]}
        ]
    }
    r = requests.post(URL, headers=headers, data=json.dumps(body))
    data = r.json()
    try:
        return data["candidates"][0]["content"]["parts"][0]["text"]
    except KeyError:
        # javab shekl-e adi nadasht (khata ya filter-e imeni) - naghshe ra neshan bede
        return "javab-e ghabel-e khandan nagereftam! status: " + str(r.status_code)

print("=== AIRO AI chat ===")
print("soalet ra benevis va Enter bezan (khorooj: exit)")

running = True
while running:
    question = input("to: ")
    if question == "exit":
        running = False
        print("khodahafez! ta jalase-ye bad.")
    else:
        answer = ask_ai(question)
        print("AI:", answer)
        print()
```

<div dir="rtl">

اجرا کن و تایپ کن: `se ta esm-e bahal baraye yek robot-e do-charkh pishnahad bede - be farsi` — جواب می‌آید: سه اسمِ بامزهٔ فارسی! یکی دیگر بپرس: `ESP32 chand pin darad?` — جواب می‌دهد. داری با کدِ پنجاه‌خطیِ خودت چت می‌کنی!

✅ **چک کن:** باید بتوانی چند سؤالِ پشتِ سرِ هم بپرسی و هر بار جوابِ AI را زیرش ببینی، و آخرش با تایپِ `exit` تمیز از حلقه بیرون بیایی. اگر این کار کرد، اولین چتِ AI ساختهٔ خودت آماده است!

دو نکتهٔ صادقانه دربارهٔ این چت. **اول:** به AI بگو «اسمِ من آیروست»، بعد بپرس «اسمِ من چیست؟» — نمی‌داند! چون هر صدازدنِ `ask_ai` یک تماسِ **کاملاً تازه** است؛ ما تاریخچهٔ گفت‌وگو را نگه نمی‌داریم و نمی‌فرستیم. چت‌های حرفه‌ای پیام‌های قبلی را هر بار همراهِ پرامپتِ جدید می‌فرستند — در تمرینِ ستاره‌دار خودت برایش حافظه می‌سازی! **دوم:** در بعضی ترمینال‌ها تایپِ فارسی به‌هم‌ریخته دیده می‌شود؛ عیب از کدت نیست — ترمینال‌ها با راست‌به‌چپ میانهٔ خوبی ندارند. راهِ عملی: سؤال را فینگلیش بنویس و داخلش بگو `be farsi javab bede`.

## چالش: Exit با E بزرگ چه می‌شود؟

اگر به‌جای `exit` بنویسی `Exit` با E بزرگ، برنامه خارج می‌شود؟ چرا؟ (یادت هست دیکشنری هم همین‌قدر سخت‌گیر بود؟)

---

**جواب:** نه، خارج نمی‌شود! شرطِ `question == "exit"` فقط با `exit`ِ کاملاً کوچک درست می‌شود. `Exit` با E بزرگ یک رشتهٔ متفاوت است، پس شرط برقرار نمی‌شود و برنامه آن را مثلِ یک سؤالِ عادی به AI می‌فرستد. کامپیوتر حروفِ بزرگ و کوچک را دو دنیای جدا می‌بیند — همان سخت‌گیری‌ای که در کلیدهای دیکشنری و JSON هم دیدی.

## ۷. چهار قانونِ دنیای AI

از امروز تا آخرِ دوره، هر جلسه AI با ماست — این چهار قانون اختیاری نیستند:

**یک: کلید مثلِ رمزِ عبور.** فقط در `secrets.py` زندگی می‌کند؛ نه در کدِ اصلی، نه در اسکرین‌شات، نه در گروه، نه در پروژهٔ عمومیِ آزمایشگاه. رویِ کلید را همیشه تار کن.

**دو: هیچ دادهٔ شخصی در prompt.** اسمِ کامل، آدرسِ خانه، اسمِ مدرسه، عکس، شماره — هیچ‌کدام به AI فرستاده نمی‌شود. پرامپتِ تو به کامپیوترهای یک شرکت می‌رود؛ چیزی را بفرست که اگر روی درِ یخچالِ خانه هم چسبیده بود، مشکلی نبود.

**سه: حساب با تأییدِ والدین.** سرویس‌های AI برای بازکردنِ حساب شرطِ سن و شرطِ اجازهٔ والدین دارند، و این شرط‌ها هم از سرویسی به سرویسِ دیگر فرق می‌کند، هم از کشوری به کشورِ دیگر. قانونِ ما ساده و همیشگی است: **حساب و کلید مالِ والدین است و تو زیرِ نظرشان کار می‌کنی** — شرطِ دقیقِ سرویسِ خودتان را هم موقعِ ثبت‌نام با هم بخوانید.

**چهار: جوابِ AI را همیشه چک کن.** این سرویس‌ها یک **فیلترِ ایمنیِ** داخلی دارند (safety settings) که پیش‌فرض روشن است و جلوی محتوای نامناسب را می‌گیرد؛ اگر روزی جوابِ خالی گرفتی، شاید همین فیلتر فعال شده. ولی هیچ فیلتری **درستی** را تضمین نمی‌کند: AI می‌تواند با اعتمادبه‌نفسِ کامل، اشتباه بگوید. فصلِ بعد این را زنده و با سند می‌بینیم!

![پوسترِ چهار قانونِ ایمنیِ AI در چیدمانِ دو-در-دو، هر کارت یک آیکونِ بزرگ و جای خالی برای متن: کارتِ ۱ کلیدِ طلایی قفل‌شده در گاوصندوقی با برچسبِ secrets.py و فلشِ اشتراکِ خط‌خورده؛ کارتِ ۲ کارتِ شناسایی و پینِ آدرسِ خانه با دایرهٔ قرمزِ ممنوع جلوی پنجرهٔ چت؛ کارتِ ۳ یک والد و نوجوان کنارِ لپ‌تاپ با سپرِ تیک‌دار؛ کارتِ ۴ حبابِ گفتارِ رباتی که با یک کتابِ باز و ذره‌بین چک می‌شود و مثلثِ هشدار؛ فقط شماره‌های ۱ تا ۴](/lesson-assets/t4-s07-first-ai-call/prompt/06-image-ai-safety-rules.png)

## واژه‌های تازه این فصل

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| Terminal | تِرمینال | پنجرهٔ متنیِ فرمان‌دادن به سیستم‌عامل — پسرعموی REPL |
| pip | پیپ | فروشگاهِ تایپیِ کتابخانه‌های Python روی کامپیوتر |
| requests | ری‌کوئستس | کتابخانهٔ HTTP در Python کامل — برادرِ بزرگِ urequests |
| POST | پُست | سفارشی که خودش بستهٔ داده دارد: «این را بگیر، جواب بساز» |
| Prompt | پرامپت | متنی که به AI می‌فرستی — سفارشِ دقیقِ تو |
| Header | هِدِر | برچسب‌های روی بستهٔ HTTP؛ کلید و نوعِ محتوا اینجا می‌روند |
| input | این‌پوت | تابعی که منتظرِ تایپِ کاربر می‌ماند و متنش را (رشته) می‌دهد |
| Model | مادِل | مغزِ مشخصی از AI که به آن پیام می‌دهی — هر سرویس چند مدل دارد |

## تمرین‌ها

اول چک‌لیستِ پایانِ فصل: در ترمینال `python --version` و `pip install requests` را با موفقیت اجرا کرده‌ای و می‌دانی هر کدام در کدام «دنیا» تایپ می‌شوند؛ کلیدت فقط در `secrets.py` است؛ اولین POST با کدِ ۲۰۰ اجرا شده و جوابِ AI را با مسیرِ `candidates[0]` تا `text` تمیز چاپ کرده‌ای؛ و چتِ ترمینالی با `input()` و پرچم کار می‌کند. اگر همه بله است، برو سراغ تمرین‌ها:

- **تمرین اجباری:** چتِ ترمینالی را راه بینداز و به دستیارت **شخصیت** بده: اولِ هر پرامپت یک جملهٔ نقش اضافه کن — مثلاً «تو یک مربیِ فوتبالِ پرانرژی هستی» یا «تو یک شاعری که فقط دوبیتی جواب می‌دهد». سه شخصیتِ مختلف را با همان یک سؤالِ ثابت امتحان کن و سه جواب را در دفترچهٔ مهندسی مقایسه کن: کدام مفیدتر بود؟ کدام خنده‌دارتر؟ فایل: `my_chat.py`.
- **تمرین ستاره‌دار ⭐:** به چتت **حافظه** بده (`my_chat_memory.py`): یک متغیرِ رشته‌ای `history` بساز؛ بعد از هر ردوبدل، سؤال و جواب را به تهش بچسبان، و دفعهٔ بعد به‌جای سؤالِ خالی، `history + question` را بفرست. حالا اسمت را بگو و دو پیام بعد بپرس «اسمِ من چیست؟» — یادش می‌ماند! فقط حواست باشد `history` خیلی بلند نشود (قانونِ بوفه!) — مثلاً فقط سه ردوبدلِ آخر را نگه دار.

## در فصل بعد

جلسهٔ بعد این دو دنیا به هم می‌رسند: سنسورهای ترم ۲ برمی‌گردند. DHT11 دما و رطوبتِ اتاقت را می‌خواند، LDR نور را، و این عددها می‌روند **داخلِ پرامپت** — و AI برایت یک گزارشِ فارسیِ آدمیزادی می‌نویسد: «اتاقت الان دم‌کرده است؛ پنجره را باز کن.» دستیارِ هواشناسیِ شخصی، ساختهٔ خودت. و یک اتفاقِ مهمِ دیگر: اولین بار مچِ AI را موقعِ **اشتباه گفتن** می‌گیریم — با سند و مدرک. از دستش نده!

</div>

---
Source: https://yaadestan.com/courses/airo/lessons/t4/s07-first-ai-call (یادستان, Yaadestan)
