HEXIS کے ساتھ قابلِ اعتماد ایجنٹ اسکلز کو اسٹیٹ مشینز میں کمپائل کریں

HEXIS کیا ہے؟

HEXIS ایک Python پیکیج اور کمانڈ لائن ٹول ہے جو ایک ایجنٹ اسکل، جس کی نمائندگی SKILL.md دستاویز کرتی ہے، کو ایک توسیع شدہ محدود حالت مشین میں مرتب کرتا ہے۔ زبان کے ماڈل سے پوری اسکل کی تشریح کروا کر ہر اگلا مرحلہ منتخب کروانے کے بجائے، HEXIS پروگراماتی حالتوں، متغیرات، شرائط اور منتقلیوں کا استعمال کرتے ہوئے کارروائیوں کی ترتیب نافذ کرتا ہے۔

زبان کے ماڈل متعلقہ حالتوں کے اندر اب بھی استدلال اور تخلیق کا کام انجام دیتے ہیں۔ تاہم، مشین طے کرتی ہے کہ اگلی کارروائی کون سی ہوگی، کون سے متغیرات دستیاب ہوں گے، لوپس کب رکنے چاہییں، اور آخری نتیجہ کون سا ہوگا۔ یہ ڈیزائن اس خطرے کو کم کرتا ہے کہ ایجنٹ اسکل میں لکھی ضروریات کو چھوڑ دے، ان کی ترتیب بدل دے، یا انہیں غلط طور پر لاگو کرے۔

HEXIS MIT لائسنس کے تحت جاری کیا گیا ہے اور فی الحال الفا سافٹ ویئر کے طور پر نشان زد ہے۔ یہ مقالے Compiling Agent Skills into Extended Finite State Machines کے ساتھ فراہم کیا گیا ہے۔

بنیادی ورک فلو

ایک عام HEXIS ورک فلو کے تین مراحل ہوتے ہیں:

1. کمپائل: ایک ماڈل اسکل دستاویز، ٹاسک ان پٹس، ٹول کی تعریفوں اور اسکل کے قواعد کو پڑھ کر ایک efsm-v1 مشین کا مسودہ تیار کرتا ہے۔ HEXIS اس کا اسکیما، گارڈز، قابل رسائی حالتیں، اختتام، شقوں کی کوریج اور ٹول حوالہ جات چیک کرتا ہے۔ ناقص مسودے نظرثانی کے لیے ماڈل کو واپس بھیج دیے جاتے ہیں۔
2. اپ ڈیٹ: نئی ایگزیکیوشن ٹریسز کو ایونٹس میں نارملائز کیا جاتا ہے۔ ہر ٹریس مرحلے کے لیے ایک ماڈل، فیصلوں کی فائل یا متعین الائنر فیصلہ کرتا ہے کہ موجودہ حالت سے مطابقت پیدا کی جائے، نئی حالت بنائی جائے، شور کو نظر انداز کیا جائے، یا ٹریس کو خارج کیا جائے۔
3. عمل درآمد: رن ٹائم موجودہ حالت سے وابستہ کارروائی انجام دیتا ہے، اعلان کردہ آؤٹ پٹس ریکارڈ کرتا ہے، اور پہلی ایسی منتقلی اختیار کرتا ہے جس کی شرط درست ثابت ہو۔

اپ ڈیٹ شدہ مشین صرف اسی وقت قبول کی جاتی ہے جب وہ مطلوبہ جانچیں پاس کرے اور نئی ٹریس کے ساتھ پہلے سے قبول شدہ ہر ٹریس کو بھی دوبارہ چلا سکے۔ اگر توثیق ناکام ہو جائے تو موجودہ مشین میں کوئی تبدیلی نہیں کی جاتی۔

اہم خصوصیات

• OpenAI کے ساتھ مطابقت رکھنے والی کمپائلیشن: کمانڈ لائن سے ماڈل، اینڈ پوائنٹ اور API کلید کے ماحولیاتی متغیر کا انتخاب کریں۔
• ٹریس پر مبنی اپ ڈیٹس: پہلے سے قبول شدہ ٹریسز کو غیر معتبر بنائے بغیر کامیاب ایگزیکیوشن کے رویے کو ایک وقت میں ایک فیصلے کے ذریعے شامل کریں۔
• قابل مطالعہ JSON مشینیں: مشینیں سادہ JSON efsm-v1 فارمیٹ استعمال کرتی ہیں، جس میں ٹائپ شدہ متغیرات اور واضح منتقلیاں شامل ہیں۔
• متعدد ایکشن اقسام: حالتیں tool، model، judge، user یا end ایکشن انجام دے سکتی ہیں۔
• محدود کنٹرول فلو: ترتیب وار گارڈز اور لوپ کاؤنٹرز برانچنگ اور دوبارہ کوشش کی حدود کو سپورٹ کرتے ہیں۔
• تیار کردہ دستاویزات: ہر معمول کی بلڈ میں GUIDE.md اور PROMPT.md شامل ہوتے ہیں۔
• فال بیک رویہ: فال بیک حالت حالیہ ترین ٹول مرحلے سے دوبارہ کوشش کرتی ہے اور ٹاسک کو اصل اسکل کی تشریح شدہ ایگزیکیوشن کے حوالے کر سکتی ہے۔
• ٹول بیک اینڈز: مشینیں OpenCode ٹولز، مقامی Bash ایگزیکیوٹر یا ماڈل کے ذریعے نافذ کیے گئے رجسٹری میں متعین ٹولز استعمال کر سکتی ہیں۔
• ہرمیٹک ٹیسٹنگ: ریپوزٹری میں 350 سے زیادہ ایسے ٹیسٹس شامل ہیں جن کے لیے API کلید، ماڈل اینڈ پوائنٹ یا نیٹ ورک کنکشن درکار نہیں ہوتا۔

انسٹالیشن اور پیشگی تقاضے

PyPI سے انسٹال کریں

HEXIS کے لیے Python 3.11 یا 3.12 درکار ہے۔ پیکیج کو pip کے ذریعے انسٹال کریں:

pip install hexis-agent

Python میں پیکیج کو hexis کے طور پر امپورٹ کیا جاتا ہے، جبکہ اس کا کمانڈ لائن ایگزیکیوٹیبل hexis-agent کہلاتا ہے۔

چیک آؤٹ سے انسٹال کریں

pip install .

pytest، Ruff، build اور Twine جیسی ڈیولپمنٹ انحصاریوں کے لیے ایڈیٹیبل انسٹالیشن استعمال کریں:

pip install -e ".[dev]"

رن ٹائم تقاضے

ماڈل پر مبنی مشینوں کو کمپائل کرنے اور چلانے کے لیے OpenAI کے ساتھ مطابقت رکھنے والا چیٹ اینڈ پوائنٹ درکار ہے۔ ڈیفالٹ ایگزیکیوشن بیک اینڈ کو OpenCode کا PATH پر موجود ہونا بھی درکار ہے۔ اگر کسی مشین کو صرف Bash درکار ہو تو --executor local منتخب کریں تاکہ کمانڈز OpenCode کے بغیر مقامی سب پروسیس میں چلیں۔

آف لائن فوری آغاز آزمائیں

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

from hexis.execution import runtime
from hexis.examples import table_clean as tc

machine = tc.reference_machine()
task = tc.gen_tasks(1, seed=0)[0]

result = runtime.run_task(
    machine,
    task,
    model=tc.build_model(),
    tools=tc.build_registry(tc.MemFS(task["files"])),
    doc=tc.skill_doc(),
)

print(
    result.stopped,
    " -> ".join(result.path()),
    tc.verify(task, result.trace),
)

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

ماڈل اینڈ پوائنٹ ترتیب دیں

HEXIS ماڈل شناخت کنندہ، بیس URL اور API کلید کمانڈ لائن آپشنز یا ماحولیاتی متغیرات سے حاصل کرتا ہے۔ بنیادی شیل ترتیب کچھ یوں ہے:

export API_KEY=your-key
export MODEL=qwen3.6-flash
export BASE_URL=https://your-endpoint/v1

آپ MODEL، BASE_URL اور API_KEY کو .env فائل میں بھی رکھ سکتے ہیں۔ HEXIS ورکنگ ڈائریکٹری سے اوپر کی سمت تلاش کرتا ہے، اور ماحول میں پہلے سے موجود متغیرات کو ترجیح حاصل ہوتی ہے۔

قابلِ استعمال اینڈ پوائنٹ آرگیومنٹس کو شیل متغیر میں رکھنے کے لیے:

M="--model qwen3.6-flash --base-url https://your-endpoint/v1"

--api-key-env NAME آپشن کلید کے لیے ایک مختلف ماحولیاتی متغیر منتخب کرتا ہے۔ API keys کمانڈ لائن پر منتقل نہیں کی جاتیں اور build manifest میں محفوظ نہیں ہوتیں۔

کسی skill کو machine میں compile کریں

کمپائلر کو skill کے path کی طرف متوجہ کریں اور output directory منتخب کریں:

hexis-agent compile \
  --skill path/to/skill \
  --out build/ \
  $M

Skill directory میں SKILL.md موجود ہونا چاہیے۔ اس میں compile.json بھی ہو سکتی ہے، جو terminals، اخذ کردہ event labels، requirements اور terminal conditions بیان کر سکتی ہے۔ اس فائل کا ہر rule اس جملے کو quote کرتا ہے جس سے وہ اخذ کیا گیا ہے۔

اگر compile.json موجود نہ ہو تو کمپائلر model سے skill سے rules اخذ کرنے کو کہتا ہے اور quoted text کو document کے خلاف جانچتا ہے۔ مؤثر configuration پھر rules.json کے طور پر محفوظ کر دی جاتی ہے۔

Build directory میں کیا شامل ہوتا ہے

• machine.json موجودہ machine محفوظ کرتی ہے۔
• machine_init.json ابتدائی compiled machine محفوظ رکھتی ہے۔
• build.json source information، command settings، model details، outcomes اور token usage ریکارڈ کرتی ہے، لیکن API key کبھی محفوظ نہیں کرتی۔
• skill/SKILL.md، tools.json اور rules.json compilation inputs محفوظ رکھتے ہیں۔
• traces/ build میں استعمال ہونے والے traces کی hashed copies رکھتا ہے۔
• progress.json trace outcomes اور machine کی حفاظت کرنے والے accepted traces ریکارڈ کرتی ہے۔
• decisions.jsonl update کے سوالات اور جوابات cache کرتی ہے۔
• report.md، context.json اور log files تشخیصی معلومات فراہم کرتی ہیں۔
• GUIDE.md inputs، tools، states، transitions، loops اور fallback behavior کی وضاحت کرتی ہے۔
• PROMPT.md ایک tool-using agent کے لیے system prompt فراہم کرتی ہے تاکہ وہ machine کو state بہ state چلا سکے۔

Machine model کو سمجھیں

HEXIS machine ایک JSON document ہے جو efsm-v1 format استعمال کرتی ہے۔ اس کے بنیادی عناصر variables، states، actions، transitions، terminals اور fallback state ہیں۔

Variables

Variables کو init_from کے ذریعے task input fields سے یا init کے ذریعے مستقل values سے initialize کیا جا سکتا ہے۔ Actions اپنے نتائج صرف declared variables میں لکھتی ہیں۔

Actions

• Model: state-specific prompt اور منتخب input variables سے declared variables generate کرتا ہے۔
• Tool: نامزد tool کو invoke کرتا ہے۔ ${command} جیسے references runtime پر substitute کیے جاتے ہیں۔
• Judge: fixed set میں سے ایک label منتخب کرتا ہے یا abstain label واپس کرتا ہے۔
• User: user input طلب کرتا ہے۔
• End: terminal result کے ساتھ execution روک دیتا ہے۔

Transitions اور guards

State کی action مکمل ہونے کے بعد transitions کو ترتیب سے evaluate کیا جاتا ہے۔ Runtime پہلی ایسی transition لیتا ہے جس کا guard درست ہو۔ خالی guard غیر مشروط ہوتا ہے اور اسے آخر میں ہونا چاہیے۔ ایک transition inc کے ذریعے counter میں اضافہ بھی کر سکتی ہے، جس سے محدود retry loops ممکن ہوتے ہیں۔

Guards ایک محدود expression language استعمال کرتے ہیں جسے hexis.machine.cond implement کرتی ہے۔ یہ mutual exclusion اور loop bounds جیسی خصوصیات کا static analysis سپورٹ کرتی ہے اور Python کا eval استعمال نہیں کرتی۔

Traces سے machine update کریں

Execution traces JSON Lines files ہوتی ہیں۔ ان کا آغاز task metadata اور verdict سے ہوتا ہے، اس کے بعد ہر سطر میں ایک event ہوتا ہے۔ ایک trace میں tool calls، model output اور ending event شامل ہو سکتے ہیں۔

پہلے زیر التوا traces کا preview دیکھیں، اس دوران model calls یا تبدیلیاں نہ کی جائیں:

hexis-agent update \
  --build build/ \
  --traces traces/ \
  --show 3

پھر update انجام دیں:

hexis-agent update \
  --build build/ \
  --traces traces/ \
  $M

ہر trace step کے لیے decider چار میں سے ایک outcome منتخب کرتا ہے:

• match موجودہ state دوبارہ استعمال کرتا ہے اور ضرورت پڑنے پر transition شامل کرتا ہے۔
• new بیان کردہ مقصد کی بنیاد پر ایک state بناتا ہے۔
• ignore harness noise کو غور سے خارج کر دیتا ہے۔
• exclude پوری trace کو خارج کر دیتا ہے۔

Model کا جواب ایک candidate state کی بھی نشاندہی کرتا ہے، step کا مقصد بیان کرتا ہے اور اسے کسی skill clause سے منسلک کر سکتا ہے۔ HEXIS نتیجے میں بننے والی candidate machine کی توثیق کرتا ہے اور اسے قبول کرنے سے پہلے تمام protected traces دوبارہ چلاتا ہے۔

Resume کریں اور update costs کو کنٹرول کریں

Model answers کو decisions.jsonl میں cache کیا جاتا ہے۔ وہی command دوبارہ چلانے پر یہ جوابات دوبارہ استعمال ہوتے ہیں، جبکہ exit status 3 کے ساتھ رکا ہوا run محفوظ progress سے resume ہو سکتا ہے۔ --no-cache صرف اس وقت استعمال کریں جب آپ جان بوجھ کر model سے دوبارہ جواب لینا چاہتے ہوں۔

ایک update میں عموماً ہر trace step کے لیے تقریباً ایک model call درکار ہوتی ہے۔ Run محدود کرنے کے لیے --max-traces N استعمال کریں۔ Model-free متبادل کے لیے --decisions FILE کے ذریعے انسانی یا بیرونی decisions فراہم کریں، یا --decider align کے ساتھ deterministic alignment منتخب کریں۔

نئی traces پر کارروائی سے پہلے HEXIS موجودہ machine کی جانچ کرتا ہے اور ہر accepted trace کو دوبارہ چلاتا ہے۔ اگر manual edit یا بدلی ہوئی tool definition نے build خراب کر دیا ہو تو command status 2 کے ساتھ ختم ہو جاتی ہے اور اس میں کوئی تبدیلی نہیں کرتی۔

Compiled machine چلائیں

Execution سے پہلے build/GUIDE.md کا معائنہ کریں۔ یہ required task inputs، دستیاب tools، state actions، transition order، retry limits اور fallback behavior کی دستاویز فراہم کرتی ہے۔

Key-value task inputs کے ساتھ machine چلائیں:

hexis-agent run \
  --machine build/ \
  --input request="Process this task" \
  --workdir work/ \
  --executor local \
  $M

مشین کے لیے متوقع ہر ان پٹ کے لیے اضافی --input KEY=VALUE اختیارات پاس کریں۔ عمل درآمد کو دوبارہ قابلِ استعمال JSON Lines ٹریس کے طور پر محفوظ کرنے کے لیے یہ شامل کریں:

--json run-trace.jsonl

طے شدہ executor OpenCode ٹولز استعمال کرتا ہے۔ مقامی executor ذیلی عمل میں Bash کمانڈز چلاتا ہے۔ رن ٹائم پر مشین صرف اپنے بیک اینڈ کے فراہم کردہ یا ٹول رجسٹری میں متعین ٹولز استعمال کر سکتی ہے؛ HEXIS خاموشی سے غائب ٹولز کو تبدیل نہیں کرتا۔

Python سے مشین استعمال کریں

بنیادی رن ٹائم انٹری پوائنٹ hexis.execution.runtime.run_task ہے۔ ایک لوڈ شدہ مشین، input آبجیکٹ پر مشتمل ٹاسک، ماڈل اڈاپٹر، ٹول رجسٹری، اور اسکل دستاویز فراہم کریں، جب fallback execution کے لیے اس کی ضرورت ہو سکتی ہو۔

from hexis.execution import runtime

result = runtime.run_task(
    machine,
    {"input": {
        "request": "Answer the question",
        "output_path": "answer.txt",
    }},
    model=model,
    tools=tools,
    doc=skill_document,
)

print(result.stopped)
print(result.path())
print(result.trace)

متعلقہ APIs میں مشینیں لوڈ کرنے کے لیے hexis.machine.schema.load_machine، endpoint کی تشکیل کے لیے hexis.llm.llm_client.client_from_env، اور گائیڈز، پرامپٹس اور Mermaid diagrams رینڈر کرنے کے لیے hexis.guide کے فنکشنز شامل ہیں۔

فراہم کردہ مثال کی مشینوں کے ساتھ کام کریں

ریپوزٹری میں examples/machines/ کے تحت چار compiled مشینیں شامل ہیں:

• dabench: computation استعمال کرتے ہوئے ڈیٹا فائل سے متعلق data-analysis سوال کا جواب دیتی ہے۔
• livemath: theorem پر مبنی multiple-choice ریاضی کے سوال کا جواب دیتی ہے۔
• sealqa: مقامی corpus سے سوال کا جواب دیتی ہے اور شواہد شامل کرتی ہے۔
• spreadsheet: ساخت تبدیل کیے بغیر workbook میں ترمیم کرتی ہے۔

یہ مشینیں عموماً shell command لکھنے کے لیے model state، اسے چلانے کے لیے tool state، returncode کی بنیاد پر guarded retries، جواب واپس پڑھنے والا tool step، اور ایسا judge state استعمال کرتی ہیں جو verified یا unverified terminal میں سے ایک منتخب کرتا ہے۔

مثال کے طور پر، LiveMath مشین اس طرح چلائیں:

hexis-agent run \
  --machine examples/machines/livemath \
  --input request="..." \
  --input output_path=answer.txt \
  --workdir work/ \
  --executor local \
  $M

مثالی مشینیں ماڈل کے بغیر لوڈ اور ساختی طور پر چیک کی جا سکتی ہیں، لیکن انہیں چلانے کے لیے configured model endpoint درکار ہوتا ہے۔

اعلیٰ درجے کی تجاویز

دستاویزات دوبارہ تیار کریں

Compilation اور updates خودکار طور پر دستاویزات تیار کرتے ہیں، جب تک کہ --no-guide استعمال نہ کیا جائے۔ انہیں دستی طور پر دوبارہ تیار کرنے کے لیے یہ چلائیں:

hexis-agent guide --build build/

آپ کمانڈ کو براہِ راست machine.json کی طرف بھی اشارہ کر سکتے ہیں۔ جب آپ generated agent prompt میں اصل skill شامل کرنا چاہیں تو --embed-skill شامل کریں، جس سے fallback کے بعد interpreted execution ممکن ہو جاتی ہے۔

واضح tool definitions فراہم کریں

جب مشین custom tools استعمال کرے تو --tools registry.json پاس کریں۔ Compilation کے دوران ٹول ناموں کو opaque identifiers سمجھا جاتا ہے۔ رن ٹائم پر registry میں متعین ٹولز کو model کے ذریعے shell commands کے طور پر نافذ کیا جا سکتا ہے، جبکہ native tools منتخب کردہ backend کو فراہم کرنے ہوں گے۔

ماڈل requests کو ایڈجسٹ کریں

Compilation اور updates میں --temperature، --max-tokens، --llm-timeout، --llm-retries، --stream، اور --extra-body JSON سمیت اختیارات دستیاب ہیں۔ Qwen-compatible endpoints کے لیے رن ٹائم reasoning کو --no-think، --think-budget، اور --judge-think-budget سے کنٹرول کیا جا سکتا ہے۔

provider-specific environment variables استعمال کریں

--provider NAME اختیار NAME_MODEL، NAME_BASE_URL، اور NAME_API_KEY پڑھتا ہے۔ MiniMax اور DeepSeek provider ناموں کے لیے built-in defaults دستیاب ہیں۔

exit statuses سمجھیں

• 0 کامیابی کی نشاندہی کرتا ہے۔
• 2 usage، configuration، یا build کے مسئلے کی نشاندہی کرتا ہے۔
• 3 model endpoint کی ناکامی یا رکاوٹ کی نشاندہی کرتا ہے؛ دوبارہ شروع کرنے کے لیے پیش رفت محفوظ کر لی جاتی ہے۔

development checks چلائیں

pytest
ruff check src tests
python -m build && twine check --strict dist/*

ٹیسٹ suite hermetic ہے۔ جب opencode executable دستیاب نہ ہو تو OpenCode سے متعلق ٹیسٹس چھوڑ دیے جاتے ہیں۔

سیکیورٹی اور رازداری

HEXIS language models کے تیار کردہ tool arguments، بشمول shell commands، چلا سکتا ہے۔ غیر معتبر workloads کو isolated environment میں چلائیں، اور صرف ان machines، skills، registries، اور task files کو استعمال کریں جن پر آپ اعتماد کرتے ہیں۔

Update process trace steps، مختصر کیے گئے tool results، اور skill clauses کو configured model endpoint پر بھیجتا ہے۔ Build directories trace copies اور model questions محفوظ رکھتی ہیں۔ اس کے علاوہ، PROMPT.md میں skill سے اخذ کردہ مکمل machine اور prompts شامل ہوتے ہیں۔ ان artifacts کو شیئر کرنے سے پہلے ان کا جائزہ لیں۔

رن ٹائم ہر model call کو اس وقت execute ہونے والی state کے prompt تک محدود رکھتا ہے، بجائے اس کے کہ ہر call کے سامنے پوری machine ظاہر کرے۔

نتیجہ

HEXIS قدرتی زبان میں دی گئی agent instructions کو واضح، validated workflows میں تبدیل کرتا ہے۔ states کے اندر model reasoning کو programmatic transitions، trace replay، محدود retries، tool restrictions، generated guides، اور fallback handling کے ساتھ ملا کر یہ skill execution کو زیادہ قابلِ پیش گوئی بنانے کا منظم طریقہ فراہم کرتا ہے۔ offline example سے آغاز کریں، ایک چھوٹی trusted skill compile کریں، generated guide کا جائزہ لیں، پھر validation results کی نگرانی کرتے ہوئے traces بتدریج شامل کریں۔