‏Semble: جستجوی کد برای ایجنت‌های هوش مصنوعی

Semble یه کتابخانه جستجوی کد ساخته‌شده برای ایجنت‌های هوش مصنوعیه. مشکلی که حل می‌کنه اینه که ایجنت‌ها معمولاً برای پیدا کردن یه تابع یا منطق خاص، کلی فایل رو کامل می‌خونن — که یعنی مصرف توکن سنگین. Semble به‌جای اون، دقیقاً همون قطعه کد مرتبط رو پیدا می‌کنه و برمی‌گردونه.

چرا Semble متفاوته؟ بنچمارک‌ها نشون می‌دن که Semble با ۹۸٪ توکن کمتر از روش grep+read به ۹۴٪ recall می‌رسه، در حالی که grep+read برای رسیدن به ۸۵٪ recall به یه context window کامل ۱۰۰k توکنی نیاز داره. کیفیت بازیابی (NDCG@10) معادل ۰.۸۵۴ هست که با مدل‌های ترنسفورمر تخصصی کد قابل مقایسه‌ست — ولی ۲۱۸ برابر سریع‌تر ایندکس می‌کنه.

زیر کاپوت چطور کار می‌کنه؟ Semble فایل‌ها رو با کمک tree-sitter به بلوک‌های کد-آگاه تقسیم می‌کنه. بعد برای هر query دو روش موازی اجرا می‌شه: جاسازی معنایی (semantic embeddings) با مدل سبک potion-code-16M و جستجوی واژگانی (lexical search) با BM25. نتایج هر دو با روش Reciprocal Rank Fusion ترکیب می‌شن. سیگنال‌های اضافی مثل بوست دادن به تعریف توابع، تشخیص identifier و کاهش رتبه فایل‌های تست هم نتایج رو بهتر می‌کنن.

می‌شه Semble رو به‌عنوان MCP server راه‌اندازی کرد تا ایجنت‌هایی مثل Claude Code، Cursor، Codex و OpenCode مستقیماً باهاش ارتباط برقرار کنن. همچنین می‌شه از طریق bash و فایل AGENTS.md یا CLAUDE.md بهش دسترسی داد — که برای ساب‌ایجنت‌هایی که نمی‌تونن مستقیم MCP رو صدا بزنن گزینه اصلیه.

استفاده به‌عنوان کتابخانه پایتون هم خیلی ساده‌ست:

from semble import SembleIndex

index = SembleIndex.from_path("./my-project")
results = index.search("save model to disk", top_k=3)
related = index.find_related(results[0], top_k=3)
result.chunk.file_path   # "model2vec/model.py"
result.chunk.content     # "def save_pretrained(self, path: PathLike, ..."

این نمونه نشون می‌ده که هر نتیجه شامل مسیر فایل، شماره خط و محتوای دقیق قطعه کده — نه کل فایل.

نکات کلیدی:

• ایندکس‌گذاری یه ریپوی معمولی ~۲۵۰ میلی‌ثانیه، پاسخ به query ~۱.۵ میلی‌ثانیه روی CPU
• بدون نیاز به GPU، API key یا سرویس خارجی
• پشتیبانی از مسیر محلی و git URL
• دستور semble savings نشون می‌ده چقدر توکن صرفه‌جویی کردی
• لایسنس MIT و قابل استفاده در پروژه‌های تحقیقاتی با citation