Dot Reflex 14B کے ساتھ زیادہ محفوظ ایجنٹ ریکوری لوپس بنائیں

Dot Reflex 14B کیا کرتا ہے

Dot Reflex 14B کوڈنگ اور ٹول استعمال کرنے والے ایجنٹس کے لیے عمل درآمد کی بحالی کا کنٹرولر ہے۔ یہ ورکر ایجنٹ کی جگہ نہیں لیتا۔ اس کے بجائے، یہ ایجنٹ کے عمل درآمد کے سفر کے مختصر JSON خلاصے کا جائزہ لیتا ہے اور سفارش کرتا ہے کہ اردگرد کا ہارنس عمل درآمد کے اگلے مرحلے کو کیسے کنٹرول کرے۔

یہ کنٹرولر GPT، Claude، Gemini، Qwen، Llama یا کسی اور ماڈل سے چلنے والے ایجنٹس کی نگرانی کر سکتا ہے، کیونکہ یہ ورکر ماڈل کے اندرونی فن تعمیر کے بجائے معمول پر لائے گئے عمل درآمدی واقعات پر کام کرتا ہے۔ یہ ریلیز Qwen3-14B-Base کے لیے rank-64 QLoRA اڈاپٹر ہے۔

Dot Reflex دس میں سے ایک کارروائی واپس کرتا ہے:

• continue: درست منصوبے کو آگے بڑھنے دیں۔
• verify: کسی دعوے یا خطرناک مفروضے کے لیے ثبوت طلب کریں۔
• retry_differently: مختلف کمانڈ، پیرامیٹر یا طریقے سے فوری کوشش دوبارہ کریں۔
• replan: ایسے طریقے کو تبدیل کریں جس کے بنیادی مفروضے ناکام ہو چکے ہوں۔
• rollback: نقصان دہ تبدیلی کے بعد معلوم درست حالت بحال کریں۔
• branch: متعدد قابلِ عمل طریقوں کو الگ ماحول میں الگ کریں۔
• switch_model: مسلسل صلاحیت یا فراہم کنندہ کی ناکامی کے بعد اگلی کوشش کسی دوسرے ماڈل کو بھیجیں۔
• ask_human: جب اختیار، راز، وضاحت یا بیرونی فیصلے کی ضرورت ہو تو توقف کریں۔
• stop_successfully: مناسب ثبوت سے تکمیل ثابت ہونے پر ختم کریں۔
• stop_failure: جب کوئی محفوظ اور مجاز بحالی باقی نہ رہے تو رک جائیں۔

آؤٹ پٹ ایک سفارش ہے، اجازت نہیں۔ اجازتوں، پالیسی کے نفاذ، ٹول کے اجرا، واپس پلٹنے کے طریقۂ کار اور رکنے کے حتمی فیصلے کی ذمہ داری آپ کے ہارنس پر برقرار رہتی ہے۔

اہم خصوصیات

• فریم ورک سے غیر وابستہ ان پٹ: کنٹرولر عمل درآمدی واقعات سے تیار کردہ عام JSON قبول کرتا ہے، جو ایجنٹ فریم ورک پہلے ہی ریکارڈ کر چکا ہو۔
• مشین کے قابلِ مطالعہ آؤٹ پٹ: ہر درست جواب میں کارروائی، جواز، اعتماد کی قدر، بحالی کی ہدایات اور پارس کی حیثیت شامل ہوتی ہے۔
• متعین جنریشن: حوالہ رن ٹائم greedy generation استعمال کرتا ہے۔
• Fail-closed رویہ: ان پٹ اسکیما یا تیار کردہ کارروائی کے غلط ہونے پر CLI غیر صفر اسٹیٹس کے ساتھ خارج ہوتا ہے۔
• متعدد انٹرفیس: کمانڈ لائن سے ایک فیصلہ چلائیں، معیاری ان پٹ کے ذریعے JSON پائپ کریں، یا مقامی HTTP endpoint کی میزبانی کریں۔
• مختلف ماڈلز کی نگرانی: ورکر ایجنٹ کے لیے Qwen استعمال کرنا یا کنٹرولر کا فن تعمیر شیئر کرنا ضروری نہیں۔

تقاضے اور تنصیب

حوالہ 4-bit رن ٹائم کے لیے Linux اور NVIDIA GPU درکار ہیں۔ ایک وقت میں ایک درخواست کے لیے 24 GB GPU عملی کم از کم ہے، جبکہ 40–48 GB اضافی گنجائش فراہم کرتا ہے۔ اس ریلیز میں GGUF، Ollama، MLX، CPU یا merged-weight builds شامل نہیں ہیں۔

ریپوزٹری کلون کریں، Python ورچوئل ماحول بنائیں اور رن ٹائم کی انحصاریات نصب کریں:

git clone https://github.com/usedotai/dot-reflex.git
cd dot-reflex
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

GitHub ریپوزٹری میں رن ٹائم، ٹیسٹ، مثالیں، دستاویزات اور جائزہ رسیدیں شامل ہیں۔ تقریباً 1.03 GB کا اڈاپٹر Hugging Face پر میزبان ہے اور پہلی بار استعمال پر خودکار طور پر ڈاؤن لوڈ ہو جاتا ہے۔ پن شدہ Qwen3 بیس ویٹس بھی Hugging Face کے ذریعے ڈاؤن لوڈ اور کیش کیے جاتے ہیں۔

ریلیز کی تصدیق کریں

ریپوزٹری کے روٹ سے Linux پر سورس پے لوڈ کی تصدیق کریں:

sha256sum --check SHA256SUMS

macOS پر نیچے دی گئی مساوی کمانڈ استعمال کریں۔ نوٹ کریں کہ macOS حوالہ GPU رن ٹائم کے لیے معاون پلیٹ فارم کے طور پر درج نہیں ہے۔

shasum -a 256 -c SHA256SUMS

آپ ماڈل لوڈ کیے بغیر سورس مینی فیسٹ، پن شدہ بیس شناخت، JSON مثالوں، اسکیما اور چارٹ رسیدوں کی توثیق کر سکتے ہیں:

python3 scripts/validate_release.py

ایجنٹ کا عمل درآمدی سفر تیار کریں

Dot Reflex خام ٹرانسکرپٹ کے بجائے ایک مختصر snapshot کی توقع کرتا ہے۔ درست ان پٹ معاہدہ trajectory.schema.json میں بیان کیا گیا ہے۔ زیادہ تر ایجنٹ سسٹمز کو ایک چھوٹے اڈاپٹر کی ضرورت ہوتی ہے جو فریم ورک سے مخصوص واقعات کو اس ساخت میں نقشہ بند کرے۔

مثال کے طور پر، فرض کریں کہ ایک ایجنٹ پاس ورڈ ری سیٹ کوڈ میں ترمیم کرتا ہے اور ٹیسٹ چلائے بغیر تکمیل کا دعویٰ کرتا ہے۔ سفر کچھ یوں ہو سکتا ہے:

{
  "task_summary": "Add password-reset token validation",
  "execution_history": [
    {
      "step": 1,
      "actor": "agent",
      "action": "Modified auth/reset.py and declared completion.",
      "result": "Patch applied; no verification was run."
    }
  ],
  "tool_results": [
    {
      "tool": "pytest",
      "status": "not_run",
      "summary": "Tests were never executed."
    }
  ],
  "current_state": "Code changed, but there is no evidence it works.",
  "detected_failure_signals": ["false_completion_risk"]
}

اس کے بعد کنٹرولر گم شدہ ثبوت کی نشان دہی کر سکتا ہے اور ایک منظم فیصلہ واپس کر سکتا ہے، مثلاً:

{
  "action": "verify",
  "rationale": "The agent claimed completion without test evidence.",
  "confidence": 0.98,
  "recovery_instructions": "Run the targeted reset-token tests, then the relevant auth suite.",
  "parse_valid": true
}

صرف وہ ثبوت شامل کریں جس کی آپ کا ہارنس درست طور پر تائید کر سکتا ہو۔ گم شدہ، پرانے یا گمراہ کن واقعات غلط سفارش کا سبب بن سکتے ہیں۔

بنیادی فیصلہ چلائیں

ریپوزٹری میں غلط تکمیل کے منظرنامے کے لیے ایک مثالی ٹریجیکٹری شامل ہے۔ اسے ون شاٹ CLI میں جمع کریں:

python3 inference.py examples/trajectory_false_completion.json \
  --adapter usedot/Dot-Reflex-14B

آپ ان پٹ پاتھ کے طور پر - استعمال کرکے معیاری ان پٹ کے ذریعے بھی ٹریجیکٹری پائپ کر سکتے ہیں:

python3 inference.py - --adapter usedot/Dot-Reflex-14B \
  < examples/trajectory_false_completion.json

آرکیسٹریٹر میں، عمل کے اختتامی اسٹیٹس اور واپس کیے گئے parse_valid فیلڈ دونوں کو چیک کریں۔ غیر صفر اختتامی اسٹیٹس اس بات کی نشاندہی کرتا ہے کہ ان پٹ اسکیمہ یا تیار کردہ ایکشن غیر معتبر ہے، اور اسے خودکار تسلسل کو روکنا چاہیے۔

Dot Reflex کو مقامی HTTP سروس کے طور پر چلائیں

اضافی سرور انحصارات انسٹال کریں اور Uvicorn کے ساتھ FastAPI ایپلیکیشن شروع کریں:

python3 -m pip install -r requirements-server.txt
uvicorn serve:app --host 127.0.0.1 --port 8080

اسی ٹریجیکٹری کو فیصلہ جاتی اینڈ پوائنٹ پر جمع کریں:

curl --fail-with-body \
  -H 'content-type: application/json' \
  --data @examples/trajectory_false_completion.json \
  http://127.0.0.1:8080/v1/decision

مثال localhost سے منسلک ہے۔ سروس کو نیٹ ورک پر ظاہر کرنے سے پہلے تصدیق، TLS، شرح کی حدود، درخواست کے حجم کی حدود، اور آڈٹ لاگنگ شامل کریں۔

کنٹرولر کو ایجنٹ لوپ میں ضم کریں

Dot Reflex کو ہر تیار کردہ ٹوکن کے بعد چلانے کے بجائے اہم شواہد کے مراحل پر چلائیں۔ مفید چیک پوائنٹس میں ناکام ٹول کال، دہرایا گیا ایکشن، کوڈ میں ترمیم، ٹیسٹ یا بلڈ کا نتیجہ، ماحول میں تبدیلی، یا تکمیل کا دعویٰ شامل ہیں۔

trajectory = harness.snapshot_for_supervisor()
decision = reflex.predict(trajectory)

if decision["action"] == "continue":
    harness.resume()
elif decision["action"] == "verify":
    harness.require_verification(
        decision["recovery_instructions"]
    )
elif decision["action"] == "ask_human":
    harness.pause_for_user(decision["rationale"])
elif decision["action"].startswith("stop_"):
    harness.stop(decision)
else:
    harness.apply_recovery_control(decision)

یہ طریقہ کار ذمہ داریوں کو الگ رکھتا ہے۔ Dot Reflex بحالی کی ضرورت کی درجہ بندی کرتا ہے، جبکہ ہارنس اصل کارروائی نافذ کرتا ہے۔ مثال کے طور پر، rollback کی تجویز کو صرف اسی وقت رول بیک پرائمیٹو چلانا چاہیے جب ہارنس نے اسے پہلے سے متعین اور مجاز کیا ہو۔

کنٹرولر کو LangGraph، OpenAI Agents SDK، OpenHands، AutoGen، CrewAI، Google ADK، یا کسی حسب ضرورت ٹول لوپ سے ان کے ایونٹس کو معمول پر لا کر منسلک کیا جا سکتا ہے۔ یہ Cursor، Claude Code، Codex CLI، یا Aider کے لیے اس وقت تک براہ راست استعمال کے قابل مڈل ویئر نہیں ہے جب تک کوئی ریپر یا ہک ان کے ایونٹ اسٹریمز کو حاصل نہ کرے۔ میپنگ کی مثالوں اور مطابقت سے متعلق نوٹس کے لیے INTEGRATION.md دیکھیں۔

اعلیٰ درجے کے انضمامی مشورے

سب سے چھوٹی فیصلہ کن تصدیق استعمال کریں

جب ایکشن verify ہو، تو دعوے کی تصدیق یا تردید کرنے کے قابل سب سے محدود چیک کو ترجیح دیں۔ کوڈنگ ورک فلو میں اس کا مطلب بڑے سوٹ سے پہلے مخصوص ٹیسٹ چلانا ہو سکتا ہے۔ نتیجہ ریکارڈ کریں اور اگلے شواہد کے مرحلے پر ایک تازہ ٹریجیکٹری جمع کریں۔

ہر ایکشن کو واضح طور پر میپ کریں

نامعلوم یا غیر معاون ایکشنز کو continue نہ سمجھیں۔ تمام دس ایکشنز کے لیے ہارنس کا رویہ متعین کریں، تیار کردہ ایکشن کی توثیق کریں، اور پارسنگ یا پالیسی چیکس ناکام ہونے پر محفوظ طریقے سے رک جائیں۔

حقیقی بحالی کے پرائمیٹو فراہم کریں

تجاویز اسی وقت مفید ہوتی ہیں جب ہارنس انہیں نافذ کر سکے۔ branch کو سپورٹ کرنے والے نظام کو الگ تھلگ ورک ٹریز یا سینڈ باکسز بنانے چاہییں۔ rollback کو سپورٹ کرنے والے نظام کو معلوم، قابلِ بحالی اچھی حالتیں برقرار رکھنی چاہییں۔ ملٹی ماڈل راؤٹر کو switch_model نافذ کرنے کے لیے حقیقی روٹنگ میکانزم درکار ہے۔

حساس فیصلوں پر انسانوں کا اختیار برقرار رکھیں

جب ایجنٹ کے پاس اختیار، راز، وضاحت، یا کسی بیرونی فیصلے کی کمی ہو تو ask_human استعمال کریں۔ ماڈل کے آؤٹ پٹ کو اکیلے تباہ کن، مالی، طبی، قانونی، سکیورٹی سے متعلق حساس، یا کسی بھی بلند اثر والی کارروائی کی اجازت دینے کی اجازت نہ دیں۔

اعتماد کو مقامی طور پر کیلیبریٹ کریں

واپس کی گئی اعتماد کی قدر تیار کردہ متن ہے، حفاظتی ضمانت نہیں۔ حدود یا آٹومیشن پالیسیوں کے اطلاق سے پہلے اپنے ماحول کی نمائندہ ٹریجیکٹریز استعمال کرکے اس کی پیمائش اور دوبارہ کیلیبریشن کریں۔

شواہد اور آڈٹ ٹریلز محفوظ رکھیں

ان پٹ ٹریجیکٹری، کنٹرولر کا جواب، نافذ کی گئی بحالی کی کارروائی، اور اس کے بعد کا نتیجہ محفوظ کریں۔ یہ رسیدیں ناکامیوں کی تفتیش آسان بناتی ہیں اور یہ جانچنے میں مدد دیتی ہیں کہ آیا کنٹرولر آپ کے ورک لوڈ پر بھی مؤثر ہے۔

تشخیصی حدود کو سمجھیں

Dot Reflex کو 6,000 مصنوعی ٹریجیکٹریز پر تربیت دی گئی اور 600 مصنوعی ٹریجیکٹریز پر توثیق کی گئی۔ شائع شدہ Agent Recovery Bench v0 تشخیص میں 1,000 متوازن الگ رکھی گئی مصنوعی ٹریجیکٹریز اور 200 علیحدہ حالت رکھنے والے مصنوعی بحالی ایپی سوڈز شامل ہیں۔

اس مصنوعی بینچ مارک پر اڈاپٹر نے 1.000 بحالی کی درستگی، 1.000 میکرو F1، اور 1.000 مصنوعی بحالی حاصل کی۔ اس کی رپورٹ کردہ اوسط تاخیر NVIDIA H200 پر 6.13 سیکنڈ تھی، لیکن یہ کسی مخصوص رَن کی پیمائش ہے، عالمگیر سروسنگ کا دعویٰ نہیں۔

مصنوعی 100% نتیجہ عالمگیر قابلِ اعتماد ہونے کا ثبوت نہیں دیتا۔ یہ بینچ مارک SWE-bench، اختتام تا اختتام ریپوزٹری مسئلہ حل کرنے کا ٹیسٹ، یا پروڈکشن ٹرائل نہیں ہے۔

شائع کردہ ڈیٹا بینچ مارک کی تقسیم سے مطابقت ظاہر کرتا ہے، لیکن آزادانہ طور پر تحریر کردہ یا پیداواری ناکامیوں میں قابلِ اعتماد منتقلی ثابت نہیں کرتا۔ نتائج کا حوالہ دینے یا تعیناتی کی پالیسیاں وضع کرنے سے پہلے EVALUATION.md کا جائزہ لیں۔

ماڈل اور رن ٹائم کی تفصیلات

• بنیادی ماڈل: Qwen/Qwen3-14B-Base۔
• طریقہ: BF16 کمپیوٹ کے ساتھ 4-bit NF4 QLoRA۔
• LoRA کنفیگریشن: رینک 64، الفا 128، اور ڈراپ آؤٹ 0.05۔
• ہدف ماڈیولز: اٹینشن اور MLP پروجیکشن لیئرز۔
• تربیتی سیاق: 2,048 ٹوکنز۔
• قابلِ تربیت پیرامیٹرز: 256,901,120، یعنی بنیادی ماڈل کا 1.710%۔
• لائسنس: ریپوزٹری اور اڈاپٹر فائلز کے لیے Apache-2.0۔

Qwen بنیادی ماڈل ایک الگ اپ اسٹریم انحصار ہے۔ مشترکہ نظام تقسیم یا تعینات کرنے سے پہلے اس کے ماڈل کارڈ اور لائسنس کا جائزہ لیں۔

نتیجہ

Dot Reflex 14B ایجنٹ کے نفاذ کے لوپس میں بحالی کی ایک منظم تہہ شامل کرتا ہے۔ GPU رن ٹائم انسٹال کرکے، موجودہ واقعات کو ٹریجیکٹری اسکیما میں تبدیل کرکے، اور CLI کے ذریعے ایک فیصلے کی جانچ کرکے آغاز کریں۔ اس کے بعد آپ HTTP سروس شامل کرسکتے ہیں یا اپنی مرضی کے ہارنس میں شواہد کے گیٹس پر کنٹرولر کو کال کرسکتے ہیں۔ نفاذ کا اختیار ہارنس میں رکھیں، ہر جواب کی توثیق کریں، آڈٹ کے شواہد محفوظ رکھیں، اور آٹومیشن فعال کرنے سے پہلے اپنی ورک لوڈ پر کارکردگی کا جائزہ لیں۔