docs: gap analysis + phased plan (session 19)

docs/planning/16-gap-analysis-and-phases.fa.md

@@ -0,0 +1,79 @@
+# تحلیل فاصله با بهترین‌ها و فازبندی سریع‌ترین مسیر — session 19 (۲۰۲۶-۱۰-۱۷)
+
+همه‌ی اعداد ما اندازه‌گیری‌شده‌اند (contributions-log §8.17–8.18)؛ اعداد رقبا از
+`docs/research/related-work-2026.md` (هر کدام با جدول مقاله‌ی منبع). معیار مشترک: SWE-bench Lite،
+زیرمجموعه‌ی ۲۷۴تایی LocAgent، Acc@k = همه‌ی محل‌های gold در k اول.
+
+## ۱. چقدر فاصله داریم؟
+
+| مرجع | file Acc@1 | func Acc@5 | ما (file@1 / func@5) | فاصله | درصدِ بهترین |
+|---|---|---|---|---|---|
+| بهترین کلی (SWE-Adept + Claude-Sonnet-4.5، API) | – | 0.878 | – / 0.485 | −0.393 | ۵۵٪ |
+| بهترین بازیاب+rerank (SweRankEmbed-L + SweRankLLM-L 32B، GPU) | 0.832 | 0.814 | 0.500 / 0.485 | −0.332 / −0.329 | ۶۰٪ |
+| بهترین بدون LLM (SweRankEmbedMulti-L 8B، GPU) | – | 0.774 | 0.485 | −0.289 | ۶۳٪ |
+| **مدل کوچکِ CPU‌پذیر (SweRankEmbed-Small 137M)** | 0.664 | 0.631 | 0.500 / 0.485 | −0.164 / −0.146 | ۷۵٪ / ۷۷٪ |
+| CodeRankEmbed 137M | 0.526 | 0.518 | 0.500 / 0.485 | −0.026 / −0.033 | ۹۵٪ / ۹۴٪ |
+| BM25 | 0.387 | 0.318 | | **+0.113 / +0.167** | ما جلوتر |
+
+**خلاصه:** در ردیف «بدون مدل، CPU، صفر توکن» تقریباً هم‌تراز CodeRankEmbed هستیم؛ تا بهترین سیستم‌ها ۳۰ تا ۴۰
+امتیاز فاصله داریم.
+
+## ۲. کشف اصلی این بررسی: مشکل در «پیدا کردن» نیست، در «مرتب کردن» است
+
+سقف rerank (اگر کسی لیست خودِ engine را کامل درست مرتب کند)، اندازه‌گیری‌شده:
+
+| مجموعه | func@5 فعلی | همه‌ی gold در ۳۰ اول | در ۱۰۰ اول | در ۳۰۰ اول | فایل: gold در ۲۰ اول |
+|---|---|---|---|---|---|
+| dev (۲۱۰) | 0.324 | 0.495 | 0.633 | **0.776** | 0.751 |
+| SWE-Gym (۲۶۶) | 0.256 | 0.470 | 0.624 | **0.748** | 0.736 |
+| Lite-274 | 0.460 | (لیست ذخیره‌شده فقط ۲۰ تا) | | | **0.887** |
+
+یعنی engine در چند ثانیه روی CPU، تابع درست را برای ~۷۵–۷۸٪ issueها در ۳۰۰ کاندید دارد (روی Lite با gold
+تک‌تابعی احتمالاً بیشتر). بهترین سیستم‌های دنیا هم دقیقاً همین ساختار را دارند: **بازیاب پرفراخوان + reranker قوی**
+(SweRank: embed → LLM listwise). تفاوت ما: بازیاب ما ایندکس embedding کل مخزن لازم ندارد.
+پس سقف واقع‌بینانه‌ی معماری فعلی با یک reranker خوب ≈ 0.70–0.78 در func@5 است — هم‌ردیف بهترین‌ها.
+
+نکته‌ی جانبی که خودش یک یافته است: اجراهای holdout نسخه‌ی v1.4.0 فقط ۲۰ تابع ذخیره کرده‌اند (پیش‌فرض محصول)، پس
+رأی dense روی Lite/Verified فقط ۲۰ کاندید دید نه ۳۰ — عدد +0.026/+0.028 محافظه‌کارانه است. لیست‌های ۳۰۰تایی
+همین الان با همان باینری بازتولید می‌شوند (`swebench/run-holdout300.sh`).
+
+## ۳. چرا کند پیش رفتیم؟ (صادقانه)
+
+| علت | سهم | قابل‌رفع؟ |
+|---|---|---|
+| **قوی‌ترین اهرم (rerank با LLM) قفل است** — هیچ کلید API اعتبار ندارد (Baseten 402→403) | خیلی زیاد | فقط پارسا: یک کلید با ~۵–۱۰ دلار |
+| CPU لپ‌تاپ ۶ هسته، بدون GPU — هر اجرای کامل ۱–۳ ساعت؛ دو اجرا هم‌زمان هر دو را کند می‌کند | زیاد | نیمه: غربال روی نیمه‌ی کوچک، cache embedding |
+| شبکه ~۲۰۰–۴۷۰ KB/s — دانلود مدل/blob ساعت‌ها | متوسط | شروع زودهنگام دانلودها به‌موازات |
+| ۱۸ session صرف تنظیم lexical شد که بازده‌اش تمام شده (precision-tuning از session 10 بسته) | زیاد در گذشته | بله: دیگر تنظیم lexical نه |
+| پروتکل سخت‌گیر (pre-registration، holdout یک‌بار) | عمدی | نه — همین مقاله را قابل‌اعتماد می‌کند |
+| dev کوچک و نامشابه Lite (gold چندتابعی) | متوسط | حل شد: split دوم SWE-Gym |
+
+## ۴. بهترین ایده (به ترتیب بازده/هزینه)
+
+1. **engine (پرفراخوان، CPU، ثانیه) + SweRankEmbed-Small روی ۱۰۰–۳۰۰ کاندید** — مدل ۱۳۷M روی CPU، فقط کاندیدها،
+   با cache بر اساس متن (issueهای یک مخزن اکثر توابع مشترک دارند). session موازی `swerank-sl` الان k=30 را می‌سنجد.
+2. **reranker listwise با LLM ارزان** روی ۲۰–۳۰ کاندید برتر (سبک SweRankLLM): طبق SweRank، GPT-4.1 روی
+   بازیاب خوب func@5 را به 0.82 رساند. با short-list ما: ~۶–۸ هزار توکن ورودی/issue → DeepSeek یا GPT-4.1-mini
+   ≈ ۰.۰۰۲–۰.۰۰۵ دلار/issue؛ کل dev+gym+Lite+Verified (~۱۳۰۰ issue) ≈ **۳ تا ۷ دلار**.
+3. فایل اول: همان reranker روی ۱۰ فایل برتر (file@20 روی Lite 0.887 است؛ file@1 فعلی 0.500).
+4. چیزهایی که **نمی‌کنیم**: fine-tune مدل روی CPU؛ تنظیم دوباره‌ی BM25F؛ LLM محلی 3B (session 17 رد شد).
+
+## ۵. فازبندی (هر فاز: دروازه‌ی از پیش ثابت، موازی هر جا ممکن)
+
+| فاز | کار | زمان | موازی با | دروازه |
+|---|---|---|---|---|
+| **P0** (در جریان) | حکم SweRankEmbed-Small k=30 روی dev+gym؛ بازتولید لیست ۳۰۰تایی Lite/Verified | ۱–۳ ساعت | هر دو هم‌زمان | func@5 ≥ +0.02 روی هر چهار نیمه |
+| **P1** | k=100 و k=300 با embedder برنده؛ cache مشترک؛ اندازه‌گیری ثانیه/issue | ½ روز | نوشتن مقاله | همان آستانه، از قبل commit |
+| **P2** | اجرای خودِ SweRankEmbed-Small روی **کل مخزن** روی CPU (هزینه‌ی ایندکس/مخزن + دقت) — جواب ریسک داور #1 | ½–۱ روز (شب) | P1 | گزارش، بدون آستانه (مقایسه‌ی هزینه) |
+| **P3** (منتظر کلید) | reranker listwise LLM روی top-20 تابع و top-10 فایل؛ اول dev-fast+gym-a (۲۰۰ issue، <۱ دلار) | ۲–۴ ساعت | P2 | file@1 یا func@5 ≥ +0.02 هر دو split |
+| **P4** | holdout یک‌بار (Lite+Verified) برای هر تصمیم P1/P3؛ انتشار v1.5.0 (`NM_DENSE` / `NM_RERANK`) | ۳–۴ ساعت | به‌روزرسانی مقاله | – |
+| **P5** | مقاله: جدول هزینه-دقت (توکن، ثانیه، GPU) — جایگاه ما روی منحنی؛ PDF | ۱ روز | P4 | – |
+| **P6** (پارسا/تیم) | holdout زبان ساده ≥۵۰ پرسش با annotator دوم — شرط main track | – | همه | – |
+
+**پیش‌بینی صادقانه:** بدون LLM (P0–P2) هدف واقع‌بینانه func@5 ≈ 0.55–0.63 روی Lite (رسیدن به
+SweRankEmbed-Small با هزینه‌ی خیلی کمتر). با reranker LLM ارزان (P3) هدف ≈ 0.70–0.80 — در ردیف بهترین‌ها با
+کسری از هزینه‌ی agentها ($0.005 در برابر $0.4–1.8 به ازای issue). این ادعا هنوز اندازه‌گیری نشده؛ فقط سقف ۰.۷۵+ اندازه‌گیری شده است.
+
+## ۶. تنها چیزی که سرعت را چند برابر می‌کند و فقط از پارسا برمی‌آید
+یک کلید API سازگار با OpenAI با ~۱۰ دلار اعتبار (DeepSeek، OpenAI، OpenRouter، Groq یا شارژ یکی از کلیدهای Baseten).
+ساختن حساب یا وارد کردن اطلاعات پرداخت را من نمی‌توانم انجام دهم. کلید را در `scratchpad/keys.json` (نه در repo) بگذار.