یه SQL agent ساختم که متن معمولی رو به کوئری‌های امن و دقیق دیتابیس تبدیل می‌کنه. این چیزیه که باعث میشه واقعاً توی پروداکشن کار کنه:

روش ساده‌لوحانه: یه بار صدا زدن LLM، دادن اسکیما، گرفتن SQL — همون لحظه‌ای که کاربر واقعی میاد سراغش می‌شکنه. سوال‌های مبهم، جدول اشتباه، بدون ریکاوری از خطا.

راه‌حل: تجزیه‌اش کردم به ۸ نود تخصصی داخل یه گراف LangGraph:
Router
Rewriter
Table Selector
SQL Generator
Validator
Executor
Synthesizer
Visualization
هر کدوم فقط یه کار انجام میدن. edgeهای شرطی هم مسئول routing و retry خودکار هستن.

نکتهٔ طلایی: حلقهٔ retry
اگه SQL یا توی validation رد بشه یا موقع اجرا fail بده، گراف برمی‌گرده به generator و خطا رو داخل کانتکست مکالمه تزریق می‌کنه. LLM می‌بینه چی نوشته بوده و چرا fail شده، و خودش اصلاحش می‌کنه.

۷ تا چیزی که فرق بین دمو و محصول واقعی رو مشخص می‌کنه:
- برای تصمیم‌های دسته‌بندی از function calling استفاده کن، نه parsing متن آزاد
- همیشه خروجی LLM رو با ground truth چک کن — مدل‌ها اسم جدول hallucinate می‌کنن
- روی retry دما رو ببر بالا که همون کوئری خراب رو دوباره نده
- کانتکست خطا رو تزریق کن — «تو X نوشتی، با Y fail شد، درستش کن»
- قبل از اجرا SQL رو validate کن — مثلاً regex برای DROP/DELETE با word boundary
- همه‌چیز رو streaming کن — کاربر نباید ۵ ثانیه به صفحه خالی نگاه کنه
- استفاده از Thread ID برای ایزوله بودن sessionها — چند کاربر، یه deployment، بدون تداخل state

سیستم خودش Vega-Lite chart هم می‌سازه. هیچ chart type ای هاردکد نشده — LLM از روی شکل داده encoding درست رو انتخاب می‌کنه.

کل کد (بک‌اند + فرانت React):
http://github.com/mallahyari/langgraph-sql-agent

توضیح معماری کامل هم داخل newsletter هست.
https://mlnotes.substack.com/p/building-a-production-ready-sql-agent

@DevTwitter | <Mehdi Allahyari/>