لـ Vercel AI SDK

أدوات بيانات محكومة لـ Vercel AI SDK.

تضيف sqai.tools() ثلاث أدوات للقراءة فقط بالضبط إلى generateText. يكتشف النموذج المصادر، ويُرسل خطة واحدة مكتوبة، ويُعيد أرقاماً يحسبها محرك حتمي — مع تجزئات تُعيد إنتاج كل إجابة.

لا يلزم مفتاح API للبدءمُدرج في سجل أدوات AI SDKai ^7.0.0 · zod ^4.0.0 · Node ≥ 20

IIالتثبيت

سطر تبعية واحد.

pnpmnpmyarnbun

جانب الخادم، Node 20 أو أحدث — في Next.js، شغِّله في معالج مسار مع runtime = \"nodejs\". التبعيات المشتركة هي ai ^7.0.0 وzod ^4.0.0، وهي الإصدارات التي تُكتب الخطط وفقها. لا حساب، ولا مفتاح، ولا ملف إعداد.

IIIبداية سريعة

أول إجابة محكومة.

import { generateText, isStepCount } from 'ai';
import { createSQAI } from '@thyn-ai/sqai-ai-sdk';

const sqai = createSQAI({
  sources: [{ name: 'orders', path: './orders.csv' }],
});

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  tools: sqai.tools(),
  stopWhen: isStepCount(12),
  prompt: 'Total revenue in the east region?',
});

تتصل createSQAI() بشكل كسول — لا شيء يُقرأ حتى أول استدعاء للأداة. تُعيد sqai.tools() مجموعة SqaiToolSet مكتوبة، دون حاجة إلى تحويل. يمنح isStepCount(12) النموذج مساحة للاكتشاف والتخطيط والتنفيذ.

أضف مصادر، لا كود ربط.

تعمل CSV وJSON والسجلات في الذاكرة وSQLite داخل العملية — لا شيء يغادر خادمك. يتصل Postgres وSnowflake وBigQuery وسواها عبر المحرك. كل مصدر يصل بالشكل المكتوب ذاته، فلا تستطيع الأدوات في المراحل اللاحقة التمييز بين CSV وSnowflake. كل مصدر، موثَّق →

const sqai = createSQAI({
  sources: [
    { name: 'orders', path: './orders.csv' },
    { name: 'sessions', provider: 'sqlite',
      path: './app.db', table: 'sessions' },
    { name: 'quotes', records: quotes },
  ],
});

كل خيار يُضيِّق النطاق.

الاقتطاع مُعلَن دائمًا؛ ولا تُعرض صفوف جزئية أبدًا. مدخلات الأداة التي يملؤها النموذج لا تحمل حقل allowed*‎ — السياسة ثابتة عند استدعاء createSQAI()‎ وتُفحص داخليًا قبل التنفيذ. لا يستطيع النموذج توسيع ما أُعطي له. نموذج الحوكمة الكامل →

const sqai = createSQAI({
  sources,
  allowedSources: ['orders'],
  allowedFields: { orders: ['region', 'revenue'] },
  allowedFunctions: 'all-readonly',
  defaultLimit: 100,
  maxRowsToModel: 25,
});

الخيارالافتراضيالأثر

sourcesمطلوب

البيانات الوحيدة التي يمكن للأدوات رؤيتها. تُسجَّل مرة واحدة — المصادر غير قابلة للتغيير.

allowedSourcesكل المسجَّلة

يُضيِّق المصادر التي يجوز لأي خطة الوصول إليها.

allowedFieldsكل الحقول

قائمة أعمدة مسموح بها لكل مصدر. كل ما عداها غير مرئي.

allowedFunctions"all-readonly"

قائمة القدرات المسموح بها — للتضييق فقط. تسمية أي شيء أوسع نطاقاً يُطلق unsupported_operation.

defaultLimit100

الصفوف المُعادة حين لا تحدد الخطة حدها الخاص.

maxExecutionRows1,000

الحد الأقصى الصارم للصفوف التي تقرأها عملية تنفيذ واحدة.

maxRowsToModel25

الصفوف التي يراها النموذج في أي وقت.

maxCellsToModel250

الخلايا التي يراها النموذج في أي وقت.

maxBytesToModel32,000

البايتات من النتيجة التي يراها النموذج في أي وقت.

IVصندوق الأدوات

ثلاث أدوات بالضبط.

الاستكشاف، والتنفيذ، والتجربة — أداة لكل منها. لن تتوسع الواجهة خلف ظهرك.

listSources

لا ينفّذ أبدًا

يُعيد حقول كل مصدر وأنواعها وأعداد صفوفها، إضافةً إلى العمليات التي يدعمها كل حقل رقمي. ثلاثة أوضاع تفصيلية تُبقي تكلفة الرموز ثابتة مع تزايد المصادر.

sum · avg · count · min · max · eq · in · gt · gte · lt · lte · is_null · is_not_null

queryData

الوحيد الذي ينفّذ

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

kind: "query" | "computation" · version: "1"
ok · needs_clarification · rejected · error

explainQuery

تشغيل تجريبي

يتحقق من الخطة ويحلّها دون لمس البيانات. الـ invocation_hash الذي يُعيده معاينة لما سيُنفَّذ — لا هاش لشيء نُفِّذ فعلًا.

invocation_hash = preview ≠ executed

Vتشغيل واحد، مطبوع

أرقام حقيقية من تشغيل حقيقي.

generateText · موجّه واحد · ثلاث خطوات أدوات

مستخدم

إجمالي الإيرادات في المنطقة الشرقية — وصافي القيمة الحالية لجدول الإيرادات بمعدل 10%؟

أداة

listSources()orders · 12 صفًا · region, revenue

أداة

queryData({ kind: "query", version: "1", … })sum(revenue) · region = "east"ok · 2130.50 · 5 طلباتplan_hash f87610d8afeb…

أداة

queryData({ kind: "computation", version: "1", … })finance.npv · rate 0.1 · values ← orders.revenueموافق · 3188.17 · 0.83 مللي ثانية

مساعد

إيرادات المنطقة الشرقية 2,130.50 موزعة على 5 طلبات. بمعدل 10%، تبلغ صافي القيمة الحالية لجدول الإيرادات 3,188.17.

لم يُجرِ النموذج أي حساب. كلا الرقمين صدرا عن المحرك الحتمي — والهاش يُعيد تشغيلهما.

VIمقارنةً بالأدوات العامة

الخطط المكتوبة بأنواع لا تتعثر.

أداة SQL عامةsqai.tools()‎

ما يكتبه النموذجأداة SQL عامةسلسلة SQL خامsqai.tools()‎خطة مكتوبة بأنواع — kind ‏"query" أو "computation"، version ‏"1"، مُتحقَّق منها بـ zod

استدعاء مشوّهأداة SQL عامةيرمي خطأً، أو يُعيد المحاولة، أو يتجاهل بصمتsqai.tools()‎يُعيد needs_clarification مع خيارات — الأدوات لا ترمي أبدًا

السؤال ذاته مرتينأداة SQL عامةSQL مختلف، إجابات مختلفةsqai.tools()‎الخطة ذاتها، الهاش ذاته — قابل للإعادة

مسار الكتابةأداة SQL عامةما تسمح به الاتصالsqai.tools()‎معدوم بالبناء — 4,574 قدرة للقراءة فقط، لا منفذ هروب يصله النموذج

الإثباتأداة SQL عامةلا شيء — رقم محتملsqai.tools()‎plan_hash وcomputation_hash على كل إجابة

أنماط الفشل على اليسار موثّقة، لا متخيَّلة: vercel/ai #1905 · #2147 · #12020 · #6913

صمّم حلقة الوكيل الكاملة →

أطلق صندوق الأدوات.

لا مفتاح API. لا حساب. أول استدعاء أداة يعمل مباشرةً.

اقرأ التوثيق →الحزمة على npm →دليل التثبيت الكامل →

مُدرَج في AI SDK Tools Registry · ai ^7.0.0 · zod ^4.0.0 · Node ≥ 20 · من جانب الخادم