From 40d358ecb54e518cf6d0f2ed4f8c08da2ee9684d Mon Sep 17 00:00:00 2001
From: Zareian <zareian.comp@gmail.com>
Date: Sat, 29 Aug 2026 02:39:48 +0330
Subject: [PATCH] readme: add RAG / AI-assistant section
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README.md
  - `rag` app row in the app table.
  - new "دستیار هوش مصنوعی (RAG)" subsection: what /api/ai/ask does now,
    the OPENAI_/QDRANT_ keys it needs, how to test it in Swagger, the
    stream flag, rag_catalog, and the internal ingest endpoints.
  - production-notes bullet updated: /api/ai/ask is real RAG when keys are
    set, no longer "stub only".

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 README.md | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 2166d3a..65ba090 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@
 | `content` | پایه‌ها، مباحث، درس‌ها، سوال‌ها، پیشرفت |
 | `progress` | آمار، لیدربرد، streak |
 | `ai_tutor` | مکالمات دستیار هوش مصنوعی |
+| `rag` | لایه‌ی RAG: بازیابی از Qdrant + تولید با GPT، پشتِ `POST /api/ai/ask` |
 | `subscription` / `payment` / `discount` | پلن، سفارش، تراکنش، کد تخفیف |
 | `notifications`, `affiliate`, `support`, `family` | امکانات جانبی |
 | `statuslog` | لاگ عمومی تغییر status، مستقل از بقیه‌ی اپ‌ها |
@@ -91,6 +92,20 @@ python manage.py createsuperuser   # اختیاری، برای /admin
 python manage.py test              # اجرای کل تست‌سوییت
 ```
 
+### دستیار هوش مصنوعی (RAG)
+
+`POST /api/ai/ask` پاسخ را از روی محتوای واقعیِ کتاب می‌سازد: embedding سوال →
+جستجوی Qdrant محدود به همان درس/فصل → تولید با GPT. تیکه‌های استفاده‌شده در
+`usedChunks` برمی‌گردند.
+
+- نیازمندِ `OPENAI_API_KEY` و `QDRANT_API_KEY` در `.env` (اپ `rag`؛ تنظیماتِ
+  `OPENAI_*` / `RAG_*` در `config/settings.py`). بدونِ کلید، همان پاسخِ stub قبلی.
+- تست در Swagger: `POST /api/ai/ask` با
+  `{"userQuestion":"...","subject":"ریاضی","grade":"ششم","lessonNumber":2}`.
+- `"stream": true` پاسخ را به‌صورت SSE توکن‌به‌توکن می‌فرستد (قراردادِ JSON بدونِ این فلگ دست‌نخورده).
+- `python manage.py rag_catalog` فهرستِ زنده‌ی collectionهای Qdrant را نشان می‌دهد (فقط‌خواندنی).
+- افزودنِ محتوای خودمان: `POST /api/rag/ingest/text` و `/api/rag/ingest/pdf` (داخلی، هدرِ `X-Internal-Key`).
+
 ---
 
 ## ۲. راهنمای دیپلوی پروداکشن
@@ -183,8 +198,8 @@ curl -i -X POST https://<host>/api/auth/session \
 - همه‌ی لاگ‌های ساختاریافته‌ی درخواست (`method`/`path`/`status`/`duration`/`user`، بدونِ
   بدنه/هدر/سکرت) روی stdout و — وقتی `LOG_DIR` ست باشه (مثلِ داخلِ Docker) — در
   `/var/log/django/app.log` نوشته می‌شن؛ قابلِ مشاهده در Grafana از طریقِ استکِ بالا.
-- `POST /api/ai/ask` فعلاً پاسخ stub برمی‌گردونه؛ محلِ اتصالِ مدلِ واقعی
-  `generate_tutor_answer` در `ai_tutor/views.py` است.
+- `POST /api/ai/ask` با تنظیمِ `OPENAI_API_KEY`/`QDRANT_API_KEY` پاسخِ واقعیِ RAG می‌دهد
+  (اپ `rag`)؛ بدونِ کلید همان stub. جزئیات: بخشِ «دستیار هوش مصنوعی (RAG)» بالاتر.
 - ارسالِ OTP از طریقِ کاوه‌نگار (`KAVENEGAR_API_KEY`) انجام می‌شه؛ شکستِ ارسال به‌جای
   موفقیتِ ساختگی، خطای صریحِ `503` برمی‌گردونه.
 - هر خطای پیش‌بینی‌نشده (نه فقط خطاهای شناخته‌شده‌ی API) همیشه پاسخِ JSON برمی‌گردونه،