آلية العمل

النموذج يقترح.
SQAI يُقرِّر.

لا يكتب الوكيل SQL ولا يُصدر كوداً للتنفيذ. يكتب طلباً مكتوب النوع — وكل طلب يسلك المسار ذاته: يُتحقَّق منه مقابل عقد مُثبَّت، ويُفحص وفق سياستك، ويُنفَّذ على محرك حتمي، ويُعاد مع التجزئات التي تُتيح إعادة تشغيله.

كل طلب — ask()‏ أو compute()‏ أو استدعاء أداة AI SDK — يسلك المسار ذاته. لا شيء يلمس المحرك حتى تجتاز كل الفحوصات.

01نية مكتوبة النوع

طلب يستطيع المحرك تحليله. لا سلسلة نصية يضطر إلى الوثوق بها.

يُصدر النموذج كائناً مكتوب النوع — لا SQL ولا كود. نية الاستعلام هي QuerySpec: مقياس يُجمَّع على مصدر مُسمَّى. نية الحساب هي ComputationSpec: دالة مُسمَّاة من العقد، مع وسائطها وارتباطاتها. اتحاد مُميَّز واحد، شكلان — وليس في أيٍّ منهما موضع تختبئ فيه سلسلة قابلة للتنفيذ.

هذا هو سطح التأليف بأكمله. ما لا يستطيع الشكل التعبير عنه، لا يستطيع النموذج طلبه.

QuerySpecالتشريح
{
"kind": "query",وسم الاتحاد — استعلام أو حساب
"version": "1",إصدار المواصفة، مُثبَّت
"source_name": "sales",مصدر متصل، بالاسم الدقيق
"metric": "revenue",العمود المراد تجميعه
"aggregation": "sum",إحدى: sum · avg · count · min · max
"group_by": "region"اختياري — تقسيم النتيجة حسب حقل
}

اختياري أيضاًfilter · limit · order

شكل الحسابmodule · function · args · kwargs · bindings · seed?

02فحص العقد

عقد واحد، مُثبَّت بالتجزئة. المجهول يُرفض مع توجيهات.

تُتحقَّق المواصفة مقابل عقد القدرات — ملف واحد مُولَّد ومُثبَّت بالتجزئة، يُدرج كل عملية وتوقيعها الدقيق وأعلام حتميتها. لا تكون القدرة قابلة للوصول إلا إذا كانت للقراءة فحسب وحتمية، أو حتمية عند تزويدها ببذرة. العمليات القادرة على الكتابة وغير الحتمية لا تُحجب في وقت التشغيل؛ بل لم تُولَّد في السطح أصلاً.

تفشل الدالة المجهولة بوصفها unsupported_operation وتُجيب بـ nearest_matches من الفهرس ذاته — فيُصحِّح النموذج نفسه بدلاً من الدوران في حلقة.

عقد القدرات

contract_hashsha256:79f1c5a6c7164e7e9e1750e70a5c03292fa87eb52d8148a740c06695924be9a1

4,778
العمليات المُدرجة في العقد
4,574
مكشوفة لـ SDK، للقراءة فحسب
4,564
حتمية تامة
10
محاكاة تستلزم بذرة
204
مستبعدة من السطح

شروط الأهليةread_only && (deterministic || deterministic_when_seeded)

عند اسم مجهولunsupported_operation + nearest_matches

03فحص السياسة

قائمة السماح لديك تُقرِّر ما إذا كان يعمل — وكيف.

تُثبَّت السياسة حين يُنشئ createSQAI()‏ النسخة، وتُطبَّق داخل العملية قبل أي تنفيذ — على المصدر، وعلى كل مقياس وتجميع وفلتر وعمود مرتبط، وعلى اسم الدالة. لا تستطيع إلا تضييق العقد: تسمية قدرة خارج السطح المؤهَّل لا تزال تُلقي unsupported_operation.

لا يحمل مدخل أداة النموذج أي حقل allowed*‏. لا شيء في الطلب يستطيع توسيع الصلاحية — فلا شيء لحقن الموجِّه أن يوسِّعه.

allowedSourcesالمصادر التي يجوز للنموذج تسميتها

  • "sales"

allowedFieldsالأعمدة التي يجوز قراءتها، لكل مصدر

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

allowedFunctionsالافتراضي — كل قدرة للقراءة فحسب، لا أكثر

  • "all-readonly"

الرفض دقيق، منسوب، نهائي

  • policy_denied_source
  • policy_denied_field
  • policy_denied_function

source: "sqai" · غير قابل لإعادة المحاولة

04محرك حتمي

مُثبَّت قبل التشغيل: float64، خيط واحد، بيئة تشغيل واحدة.

أولاً، تُحلُّ الارتباطات. سمَّى النموذج مصدراً وحقلاً؛ فتسحب SQAI القيم الفعلية عبر الأداة الأولية extractColumns المحاذية للصفوف في المحرك، مع معالجة القيم الخالية زوجياً. لا تُضمِّن SQAI المصفوفات بنفسها — فالمدخل الذي يُجزَّأ هو بالضبط المدخل الذي نُفِّذ.

عندها فحسب يلمس الطلب المحرك. بيئة التشغيل موقَّعة ومُصدَّرة ومُثبَّتة: دقة float64، خيط واحد. أول compute()‏ يُهيِّئها مرة واحدة في نحو 110 ثوانٍ؛ بعدها تبقى مقيمة — يقيس finance.npv‏ بين 0.83 و0.93 مللي ثانية دافئاً.

غلاف الحتمية
runtime_bundle_version0.1.0
runtime_bundle_sha2564d64142e4c1ff63d299cfc8b172fdf97cb59169b545e1e02978e678a632ce6e1
platformdarwin
architecturearm64
precision_modefloat64
thread_count1
seed—
input_hash2ea5ede72acd2912fe9e1230cef34afad4c9436bfa8a709bac2da02b478e3212

يُسجَّل مع كل نتيجة — يُحدِّد الغلاف نطاق الضمان بدلاً من المبالغة في ادعائه.

05الإجابة + المصدر

تجزئتان. واحدة قبل، وواحدة بعد.

تُختم invocation_hash قبل التنفيذ — على الوحدة والدالة والوسائط والارتباطات المحلولة والبذرة والعقد والنطاق. تُختم computation_hash بعده: تجزئة الاستدعاء مطوية مع النتيجة القانونية. إعادة التشغيل تعني تنفيذه مجدداً ومقارنة البايتات.

يشترك كلا SDK في مُسلسِل قانوني واحد، فالحساب ذاته يُنتج تجزئات متطابقة بايتاً في TypeScript وPython. تحمل إجابات الاستعلام الانضباط ذاته: plan_hash على الخطة المحلولة القانونية، إضافة إلى مسار القرار والنطاق الدقيق الذي نُفِّذ فيه.

3188.1687606249325finance.npv · مرتبط بعمود حي · 0.83 مللي ثانية دافئاً

مختوم قبل التنفيذ

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({ … })

    هل سيعمل؟

    تشغيل تجريبي. يُعيد الخطة المحلولة والثقة وتجزئة استدعاء أولية — معاينة فحسب، لا تجزئة منفّذة.

  4. 04queryData({ … })

    شغّله.

    الأداة الوحيدة التي تنفّذ. تُعيد النتيجة مع سلسلة إثباتها كاملة؛ النتائج الضخمة تبقى قابلة للاسترداد عبر result_id.

الأدوات لا تُلقي استثناءات — كل مخرج محدد النوعok · needs_clarification · rejected · error

الآليات، حقلًا بحقل.

اقرأ التوثيق →