یہ کیسے کام کرتا ہے

ماڈل تجویز کرتا ہے۔
SQAI نمٹاتا ہے۔

ایجنٹ نہ SQL لکھتا ہے، نہ چلانے کے لیے کوئی کوڈ خارج کرتا ہے۔ وہ ایک typed درخواست لکھتا ہے — اور ہر درخواست ایک ہی راستے سے گزرتی ہے: ایک pinned معاہدے کے خلاف تصدیق، آپ کی پالیسی کے خلاف جانچ، ایک deterministic انجن پر عمل، اور ان hashes کے ساتھ واپسی جو اسے دوبارہ چلا سکتے ہیں۔

ہر درخواست — ask()، compute()، یا AI SDK tool call — ایک ہی راستے سے گزرتی ہے۔ جب تک ہر جانچ پاس نہ ہو، کچھ بھی انجن کو نہیں چھوتا۔

01Typed ارادہ

ایک درخواست جسے انجن parse کر سکے — نہ کہ ایک string جس پر اعتماد کرنا پڑے۔

ماڈل ایک typed آبجیکٹ خارج کرتا ہے — نہ SQL، نہ کوڈ۔ query intent ایک QuerySpec ہے: ایک named source پر aggregate کرنے کے لیے ایک metric۔ computation intent ایک ComputationSpec ہے: معاہدے سے ایک named فنکشن، arguments اور bindings کے ساتھ۔ ایک discriminated union، دو شکلیں — اور کہیں بھی کوئی جگہ نہیں کہ کوئی executable string چھپ سکے۔

یہی پوری authoring surface ہے۔ جو شکل ظاہر نہیں کر سکتی، ماڈل اس کا مطالبہ نہیں کر سکتا۔

QuerySpecساخت
{
"kind": "query",union tag — query یا computation
"version": "1",spec کا ورژن، pinned
"source_name": "sales",ایک منسلک source، بالکل درست نام سے
"metric": "revenue",aggregate کرنے کا column
"aggregation": "sum",sum · avg · count · min · max میں سے ایک
"group_by": "region"اختیاری — نتیجے کو کسی field سے تقسیم کریں
}

یہ بھی اختیاریfilter · limit · order

computation کی شکلmodule · function · args · kwargs · bindings · seed?

02معاہدے کی جانچ

ایک معاہدہ، hash-pinned۔ نامعلوم کو ہدایت کے ساتھ رد کیا جاتا ہے۔

spec کو capability معاہدے کے خلاف validate کیا جاتا ہے — ایک generated، hash-pinned فائل جس میں ہر operation، اس کا exact signature، اور اس کے determinism flags درج ہیں۔ کوئی capability صرف تبھی قابلِ رسائی ہے جب وہ read-only اور deterministic ہو، یا seeded ہونے پر deterministic ہو۔ Write-capable اور non-deterministic operations کو runtime پر نہیں روکا گیا — وہ surface میں generate ہی نہیں ہوئے۔

کوئی نامعلوم فنکشن unsupported_operation کے طور پر ناکام ہوتا ہے اور اسی index سے nearest_matches کے ساتھ جواب دیتا ہے — ماڈل loop کرنے کے بجائے خود کو درست کر لیتا ہے۔

Capability معاہدہ

contract_hashsha256:79f1c5a6c7164e7e9e1750e70a5c03292fa87eb52d8148a740c06695924be9a1

4,778
معاہدے میں درج operations
4,574
SDKs کو دستیاب، read-only
4,564
مکمل طور پر deterministic
10
بیج-ضروری سمیولیشنز
204
surface سے خارج

اہلیتread_only && (deterministic || deterministic_when_seeded)

نامعلوم نام پرunsupported_operation + nearest_matches

03پالیسی جانچ

آپ کی allow-list طے کرتی ہے کہ یہ چلے گا یا نہیں — اور کیسے۔

پالیسی اس وقت مقرر ہو جاتی ہے جب createSQAI() instance بناتا ہے، اور کچھ بھی execute ہونے سے پہلے in-process نافذ ہوتی ہے — source پر، ہر metric، group، filter، اور bound column پر، اور فنکشن کے نام پر۔ یہ صرف معاہدے کو محدود کر سکتی ہے: eligible surface سے باہر کسی capability کا نام لینا پھر بھی unsupported_operation پھینکتا ہے۔

ماڈل کے tool input میں کوئی allowed* field نہیں ہوتا۔ درخواست میں کچھ بھی رسائی نہیں بڑھا سکتا — لہٰذا prompt injection کے لیے بڑھانے کو کچھ ہے ہی نہیں۔

allowedSourcesوہ sources جن کا نام ماڈل لے سکتا ہے

  • "sales"

allowedFieldsوہ columns جو وہ پڑھ سکتا ہے، فی source

  • sales.region
  • sales.revenue
  • sales.order_date

allowedFunctionsپہلے سے طے — ہر read-only capability، اس سے زیادہ کچھ نہیں

  • "all-readonly"

انکار درست، منسوب، اور حتمی ہے

  • policy_denied_source
  • policy_denied_field
  • policy_denied_function

source: "sqai" · دوبارہ قابلِ کوشش نہیں

04Deterministic انجن

چلنے سے پہلے pinned: float64، ایک thread، ایک runtime۔

پہلے، bindings resolve ہوتی ہیں۔ ماڈل نے ایک source اور ایک field کا نام لیا؛ SQAI انجن کے row-aligned extractColumns primitive کے ذریعے اصل قدریں نکالتا ہے، nulls کو pairwise سنبھالتے ہوئے۔ SQAI خود arrays کو zip نہیں کرتا — لہٰذا جو input hash ہوتا ہے وہ بالکل وہی input ہے جو execute ہوا۔

صرف اب درخواست انجن کو چھوتی ہے۔ runtime signed، versioned، اور pinned ہے: float64 precision، ایک single thread۔ پہلا compute() اسے ایک بار provision کرتا ہے، تقریباً 110 سیکنڈ میں؛ اس کے بعد یہ resident رہتا ہے — finance.npv warm پر 0.83–0.93 ms ناپتا ہے۔

تعینیت کا دائرہ
runtime_bundle_version0.1.0
runtime_bundle_sha2564d64142e4c1ff63d299cfc8b172fdf97cb59169b545e1e02978e678a632ce6e1
platformdarwin
architecturearm64
precision_modefloat64
thread_count1
seed—
input_hash2ea5ede72acd2912fe9e1230cef34afad4c9436bfa8a709bac2da02b478e3212

ہر نتیجے کے ساتھ ریکارڈ کیا جاتا ہے — envelope ضمانت کا دائرہ بیان کرتا ہے، بڑھا چڑھا کر نہیں۔

05جواب + ماخذ

دو hashes۔ ایک پہلے، ایک بعد۔

invocation_hash execution سے پہلے لگایا جاتا ہے — module، function، arguments، resolved bindings، seed، contract، اور scope پر۔ computation_hash بعد میں لگایا جاتا ہے: invocation hash کو canonical نتیجے کے ساتھ fold کر کے۔ Replay کا مطلب ہے اسے دوبارہ چلائیں اور bytes کا موازنہ کریں۔

دونوں SDKs ایک canonical serializer شیئر کرتے ہیں، لہٰذا ایک ہی computation TypeScript اور Python میں byte-identical hashes دیتا ہے۔ Query جوابات بھی یہی ضبط رکھتے ہیں: canonical resolved plan پر ایک plan_hash، فیصلے کا راستہ، اور وہ exact scope جس میں یہ چلا۔

3188.1687606249325finance.npv · ایک live column سے bound · 0.83 ms warm

execution سے پہلے لگایا گیا

invocation_hash

8223a694250fc751fcf8a7777b8e1f524c44ff1f0e7e83451467f554a6123950

ماڈیول · فنکشن · آرگیومنٹس · ریزولوڈ بائنڈنگز · سیڈ · کنٹریکٹ · اسکوپ

ایگزیکیوشن کے بعد مہر لگائی گئی

computation_hash

ff5280ea128113f528dd1e9a28b9bc4a81469075ed7c981c7176fb172d98085d

انووکیشن ہیش، کینونیکل نتیجے کے ساتھ ضم شدہ

TypeScript اور Python میں بائٹ-یکساں — ایک زبان میں حاصل شدہ نتیجہ دوسری میں ری پلے اور تصدیق ہوتا ہے۔

دونوں کا حساب لگایا گیاcontract_hash sha256:79f1c5a6…

کوئری پلین پرplan_hash f87610d8afeb…decision_path "exact_spec"deterministic_scope "local_registered_source"

06دریافت کا چکر

اندازہ نہیں — دریافت کریں، ڈرائی رن کریں، پھر ایگزیکیوٹ کریں۔

فیلڈ کے نام اور فنکشن سگنیچر دریافت کیے جاتے ہیں، گھڑے نہیں جاتے۔ AI SDK صرف تین ٹولز سامنے رکھتا ہے — اور ان میں سے صرف ایک ایگزیکیوٹ کرتا ہے۔

  1. 01listSources()

    میں کیا چھو سکتا ہوں؟

    منسلک سورسز، بالکل درست فیلڈ ناموں، اقسام، اور ہر فیلڈ پر اجازت یافتہ آپریشنز کے ساتھ۔ کبھی ایگزیکیوٹ نہیں ہوتا۔

  2. 02listSources({ capabilitySearch: "npv" })

    میں کیا کمپیوٹ کر سکتا ہوں؟

    وہی ٹول، ڈیٹرمنسٹک کیٹلاگ میں تلاش کرتا ہے — مطابق ماڈیولز، درست سگنیچرز، اور یہ کہ سیڈ درکار ہے یا نہیں۔

  3. 03explainQuery({ … })

    کیا یہ چلے گا؟

    ڈرائی رن۔ ریزولوڈ پلان، اعتماد، اور ایک پیش نظارہ invocation_hash واپس کرتا ہے — پیش نظارہ، کبھی ایگزیکیوٹڈ ہیش نہیں۔

  4. 04queryData({ … })

    چلائیں۔

    وہ واحد ٹول جو ایگزیکیوٹ کرتا ہے۔ نتیجہ اور اس کی مکمل پروویننس واپس کرتا ہے؛ بڑے نتائج result_id سے قابلِ بازیافت رہتے ہیں۔

ٹولز کبھی ایرر نہیں پھینکتے — ہر نتیجہ ٹائپڈ ہےok · needs_clarification · rejected · error

میکانکس، فیلڈ بہ فیلڈ۔

دستاویزات پڑھیں →