ToolReplay کے ذریعے AI ایجنٹ کی ٹول کالز کا آڈٹ

ToolReplay کیا کرتا ہے

ToolReplay حقیقی ٹولز کو چلائے بغیر ریکارڈ شدہ AI ایجنٹ ٹول کالز کا آڈٹ کرتا ہے۔ یہ ٹرانسکرپٹ کا جائزہ لے کر تین مسائل کی نشان دہی کرتا ہے: غیر متعین جوابات، غیر ضروری کالز، اور ایجنٹ کی اعلان کردہ اجازتوں سے باہر کی کالز۔ یہ ٹرانسکرپٹ کو SHA-256 ہیش چین میں محفوظ بھی کر سکتا ہے اور تصدیق کر سکتا ہے کہ محفوظ کی گئی فائل میں ترمیم نہیں کی گئی۔

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

ToolReplay انسٹال اور چلائیں

ToolReplay کے لیے Python 3.11 یا اس کے بعد کا ورژن درکار ہے اور رن ٹائم پر کسی تیسرے فریق کی dependency کی ضرورت نہیں ہوتی۔ یہ نیٹ ورک تک رسائی نہیں کرتا۔

سورس checkout سے ماڈیول براہِ راست چلائیں:

python -m toolreplay version

آپ console script بھی انسٹال کر سکتے ہیں:

pip install .
toolreplay version

دونوں طریقے انسٹال شدہ ورژن دکھاتے ہیں، مثلاً:

toolreplay 0.6.0

ٹرانسکرپٹ کا فارمیٹ سمجھیں

ٹرانسکرپٹ JSON Lines فائل ہوتی ہے۔ ہر غیر خالی سطر ایک ٹول invocation کی نمائندگی کرتی ہے اور اس میں بالکل چار فیلڈز ہونا ضروری ہیں:

• index: ایک integer جو 0 سے شروع ہوتا ہے اور بالکل 1 کے اضافے سے بڑھتا ہے۔
• tool: کال کیے گئے ٹول کا نام۔
• args: ٹول کے arguments پر مشتمل object۔
• response: ریکارڈ شدہ ٹول response پر مشتمل object۔

ایک درست record یوں نظر آتا ہے:

{"index": 4, "tool": "write_file", "args": {"path": "docs/intro.md", "text": "edited"}, "response": {"ok": true}}

Parsing جان بوجھ کر سخت رکھی گئی ہے۔ نامعلوم فیلڈز، غائب فیلڈز، غلط object types، non-integer indexes اور ترتیب سے باہر indexes سخت error کا باعث بنتے ہیں۔ Boolean values کو integer کے طور پر قبول نہیں کیا جاتا، اگرچہ Python میں bool، int کی subclass ہے۔

ToolReplay کالز کا موازنہ canonical JSON کے ذریعے کرتا ہے: ٹول کا نام اور arguments کو sorted keys اور غیر ضروری whitespace کے بغیر encode کیا جاتا ہے۔ لہٰذا مختلف key ordering والے argument objects پھر بھی ایک ہی کال کی نمائندگی کرتے ہیں۔ جب ToolReplay determinism چیک کرتا ہے تو responses کے لیے بھی یہی canonical encoding استعمال ہوتی ہے۔

Replay آڈٹ چلائیں

replay کمانڈ ٹرانسکرپٹ کو اس کے اپنے ریکارڈ شدہ responses کے مقابل چیک کرتی ہے۔ repository میں شامل خراب sample کو آزمائیں:

python -m toolreplay replay samples/session-dirty.jsonl

یہ کمانڈ ایک deterministic، سطر بہ سطر report تیار کرتی ہے:

calls: 6
divergence: index 5
findings: 2
index 2: redundant-call: tool 'read_file' repeats the identical call at index 1 with no state change between them
index 5: non-determinism: tool 'search' returned a different response than the identical call at index 3

header اوپر سے نیچے پڑھا جاتا ہے۔ calls: 6 کا مطلب ہے کہ چھ درست records parse کیے گئے۔ divergence: index 5 اس پہلے مقام کی نشان دہی کرتا ہے جہاں deterministic دوبارہ اجرا ریکارڈنگ سے مختلف ہو گا۔ findings: 2 اس کے بعد آنے والی findings کی تعداد بتاتا ہے۔

Findings کو پہلے index اور پھر kind کے لحاظ سے sort کیا جاتا ہے، اس لیے ایک ہی input کے بار بار کیے گئے audits کا output byte-identical ہوتا ہے۔

غیر تعینیت

ToolReplay ہر canonical call کے لیے پہلا response یاد رکھتا ہے۔ اگر بعد میں اسی جیسی کال کا ریکارڈ شدہ response مختلف ہو تو یہ غیر تعینیت کی report کرتا ہے۔ Sample میں install کے لیے search کال indexes 3 اور 5 پر ظاہر ہوتی ہے، لیکن responses میں hit counts مختلف ہیں۔ Index 5 divergence point بن جاتا ہے۔

یہ agents کے لیے اہم ہے، کیونکہ پہلے جواب کی بنیاد پر کیا گیا فیصلہ بدل سکتا تھا اگر دوسرا جواب واپس کیا جاتا۔ یہ finding ظاہر کرتی ہے کہ session ایسی معلومات پر منحصر ہے جو ریکارڈنگ کے اندر مستحکم نہیں۔

غیر ضروری کالز

دہرائی گئی کال صرف اسی وقت غیر ضروری ہوتی ہے جب دونوں کالز کے درمیان کوئی ریکارڈ شدہ event ایسا نہ ہو جو state تبدیل کر سکتا ہو۔ Default mutators یہ ہیں: write_file، delete_file، create_file، move_file اور run_command۔ یکساں کالز کے درمیان کوئی بھی مختلف کال بھی احتیاطاً ممکنہ state change سمجھی جاتی ہے۔

Sample میں read_file، docs/intro.md کو indexes 1 اور 2 پر پڑھتا ہے اور درمیان میں کوئی state change نہیں ہوتا، اس لیے index 2 کو flag کیا جاتا ہے۔ write_file کال کے بعد کی گئی بعد والی read کو redundant نہیں سمجھا جائے گا۔

ایجنٹ کی اجازتیں چیک کریں

جب ایجنٹ کے لیے permission declaration موجود ہو تو scope استعمال کریں:

python -m toolreplay scope samples/session-dirty.jsonl samples/scope.json

Sample یہ output تیار کرتا ہے:

calls: 6
findings: 1
index 4: permission-overreach: tool 'write_file' is not in the declared scope for agent 'docs-reader'

Replay اور scope کو جان بوجھ کر الگ کمانڈز رکھا گیا ہے۔ Replay کسی session کا اسی session کے مقابل جائزہ لیتا ہے اور اسے صرف ٹرانسکرپٹ درکار ہوتا ہے۔ Scope ہر کال کا موازنہ ایک الگ permission file سے کرتا ہے۔

Scope file ایک JSON object ہوتی ہے جس میں ایجنٹ کا نام اور اجازت یافتہ ٹولز کی مکمل فہرست شامل ہوتی ہے:

{"agent": "docs-reader", "allowed_tools": ["read_file", "list_dir", "search"]}

ٹول کے ناموں کا موازنہ بالکل اسی صورت اور case-sensitive انداز میں کیا جاتا ہے۔ غائب فیلڈز، غلط types یا non-string entries مسترد کر دی جاتی ہیں۔ Scope checking نام کی بنیاد پر ہوتی ہے؛ یہ arguments کا جائزہ نہیں لیتی اور یہ تعین نہیں کرتی کہ اجازت یافتہ ٹول کسی اجازت یافتہ path کو target کرتا ہے یا نہیں۔

ٹرانسکرپٹ محفوظ کریں

seal کمانڈ ٹرانسکرپٹ کو hash-chained JSONL فائل میں تبدیل کرتی ہے:

python -m toolreplay seal samples/session-dirty.jsonl > sealed.jsonl

ہر سیل شدہ لنک میں اصل ریکارڈ کے فیلڈز کے ساتھ prev اور digest بھی شامل ہوتے ہیں۔ پہلا لنک پچھلے ڈائجسٹ کے طور پر 64 صفر والے ہیکساڈیسیمل حروف استعمال کرتا ہے۔ ہر بعد کا SHA-256 ڈائجسٹ پچھلے ڈائجسٹ اور موجودہ ریکارڈ کے کینونیکل بائٹس کو شامل کرتا ہے، جن میں اس کا انڈیکس، ٹول، دلائل اور جواب شامل ہیں۔

چونکہ ہر لنک پچھلے لنک پر منحصر ہوتا ہے، اس لیے پہلے کے کسی ریکارڈ میں تبدیلی سے اس ریکارڈ کا ڈائجسٹ اور اس کے بعد کے تمام ڈائجسٹ تبدیل ہو جاتے ہیں۔ یوں یہ سلسلہ تبدیلیوں کو نمایاں کرتا ہے اور پہلے ٹوٹے ہوئے لنک کا مقام بتاتا ہے۔

سیل شدہ فائل کی تصدیق کریں

درست سلسلے کی تصدیق اس کمانڈ سے کریں:

python -m toolreplay verify sealed.jsonl

غیر تبدیل شدہ فائل یہ نتیجہ دیتی ہے:

chain: intact

اگر ریکارڈ شدہ جواب یا سلسلے کے کسی بھی دوسرے فیلڈ میں تبدیلی کی جائے تو تصدیق پہلے ٹوٹے ہوئے لنک، متوقع ڈائجسٹ اور حاصل شدہ ڈائجسٹ کی اطلاع دیتی ہے:

chain: broken
first broken link: index 3
expected: 34d19a9dfb112baa07afa37994ddcbbebe2973674385f3942340653d08d205bd
found: 40aadf3b8156217f0b5b1d95010b6b79f82a26ccf5e780aed0f5f311f865028a

سیل کرنے سے سیل کرنے کے بعد ہونے والی تبدیلیوں کا پتا چلتا ہے، جن میں ترتیب، انڈیکسز، ٹولز، دلائل اور جوابات میں تبدیلیاں شامل ہیں۔ یہ ڈیجیٹل دستخط نہیں ہے: جو بھی شخص فائل میں ترمیم کر سکتا ہے، وہ اسے دوبارہ سیل بھی کر سکتا ہے۔ ماخذ کی صداقت ثابت کرنے کے لیے حتمی ڈائجسٹ پر ایسی کلید سے دستخط کرنا ضروری ہوگا جس کا انتظام ToolReplay سے باہر کیا جاتا ہو۔

CI میں ToolReplay استعمال کریں

ToolReplay کے ایگزٹ کوڈز اسے بلڈ گیٹس کے لیے موزوں بناتے ہیں:

• 0: آڈٹ صاف ہے یا سلسلہ درست ہے۔
• 1: نتائج موجود ہیں یا سلسلہ ٹوٹا ہوا ہے۔
• 2: استعمال کی خرابی پیش آئی، جیسے غلط فارمیٹ والا اِن پٹ یا فائل کا غائب ہونا۔

CI جاب میں ری پلے اور اسکوپ چیکس براہِ راست چلائیں:

python -m toolreplay replay session.jsonl
python -m toolreplay scope session.jsonl scope.json

ایگزٹ کوڈ 1 کا مطلب ہے کہ ٹول نے اپنا آڈٹ مکمل کیا اور رپورٹ کرنے کے لیے کچھ پایا۔ ایگزٹ کوڈ 2 کا مطلب ہے کہ آڈٹ چل ہی نہیں سکا، اس لیے آٹومیشن غلط فارمیٹ والے اِن پٹ کو حقیقی نتیجے سے الگ سمجھ سکتی ہے۔

قابلِ تکرار موازنوں کے لیے ہر رَن کو سیل کریں اور نتائج کا فرق دیکھیں:

python -m toolreplay seal run-a.jsonl > run-a.sealed.jsonl
python -m toolreplay seal run-b.jsonl > run-b.sealed.jsonl
git --no-pager diff --no-index run-a.sealed.jsonl run-b.sealed.jsonl

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

اعلیٰ درجے کا استعمال اور عملی حدود

• ٹرانسکرپٹس کو اضافے کے لیے موزوں رکھیں۔ JSON Lines پروڈیوسر کو ہر کال کا ایک ریکارڈ شامل کرنے دیتا ہے اور ورژن کنٹرول میں تبدیلیوں کا جائزہ آسان بناتا ہے۔
• ریکارڈ شدہ جوابات محفوظ رکھیں۔ ری پلے حقیقی ٹولز کو کال نہیں کرتا؛ یہ صرف ان مسائل کا پتا لگا سکتا ہے جو ٹرانسکرپٹ میں موجود ہوں۔
• اضافیت کی محتاط تشریح کریں۔ ڈیفالٹ میوٹیٹر فہرست مقرر ہے، اور اس فہرست میں شامل نہ ہونے والے حسبِ ضرورت تبدیلی کرنے والے ٹولز کو اضافیت کے تجزیے میں صرف پڑھنے والے ٹولز سمجھا جاتا ہے۔
• موازنے کی حد یاد رکھیں۔ غیر تعینیت کا پتا صرف اس وقت چلتا ہے جب ایک ہی کینونیکل کال دہرائی جائے۔ معنوی طور پر متعلقہ جوابات والی مختلف کالز کو مساوات کے لیے جانچا نہیں جاتا۔
• اختیار اور ہدف بندی الگ رکھیں۔ اسکوپ چیکس صرف ٹول کے ناموں کو جانچتے ہیں۔ یہ اس بات کا پتا نہیں لگا سکتے کہ اجازت یافتہ ٹول کسی ممنوعہ وسیلے پر استعمال ہوا ہے۔
• سیلنگ کو سالمیت کے لیے استعمال کریں، شناخت کے لیے نہیں۔ سلسلہ دکھاتا ہے کہ سیل کرنے کے بعد فائل تبدیل ہوئی یا نہیں، لیکن یہ ثابت نہیں کرتا کہ سلسلہ کس نے بنایا۔

ٹیسٹ سوٹ چلائیں

یہ پروجیکٹ Python کے معیاری لائبریری والے unittest فریم ورک کا استعمال کرتا ہے اور اس کے لیے کسی تیسرے فریق کی ٹیسٹ انحصاری درکار نہیں۔ ریپوزٹری کی جڑ سے یہ کمانڈ چلائیں:

python -m unittest discover -s tests

ٹیسٹس سخت ٹرانسکرپٹ پارسنگ، کینونیکل انکوڈنگ، ہیش سلسلہ بنانے اور چھیڑ چھاڑ کا پتا لگانے، ری پلے نتائج، اسکوپ نفاذ، CLI کے رویے اور ایگزٹ کوڈز کا احاطہ کرتے ہیں۔

نتیجہ

ToolReplay، AI ایجنٹ سیشنز کے لیے ایک مرکوز آڈٹ ورک فلو فراہم کرتا ہے۔ غیر مستقل یا غیر مؤثر رویے کا پتا لگانے کے لیے replay سے شروع کریں، اعلان کردہ ٹول اجازتوں کی جانچ کے لیے scope استعمال کریں، اور ریکارڈنگ کے بعد ہونے والی تبدیلیوں کا پتا لگانے کے لیے seal کے ساتھ verify استعمال کریں۔ اس کی سخت اِن پٹ توثیق اور متعین رپورٹس اسے ڈیبگنگ، جائزے، ورژن کنٹرول اور CI نفاذ کے لیے عملی بناتی ہیں۔