SDK وسطر الأوامر
@azothos/sdk وواجهة v1 REST API
طريقان للدخول. أرسل الاستدعاءات عبر البوابة الخاضعة للحوكمة بأي عميل متوافق مع OpenAI — وهو المسار الذي تُطبَّق فيه القواعد وتُختم فيه القرارات — أو أبلِغ عن الاستدعاءات التي تجري في مكان آخر بمُغلِّفات SDK.
التثبيت
npm install @azothos/sdkالإصدار 18 من Node.js أو أحدث، ومفتاح API من الإعدادات › الوصول (az_live_… أو az_test_…). وتتحقق حزمة SDK من شكل المفتاح قبل أي طلب.
عبر البوابة
وجّه عميل OpenAI إلى https://www.azothos.ai/api/v1 — أو إلى مضيفك الخاص في الاستضافة الذاتية. تبني الدالة azothGatewayHeaders ترويسات Azoth وتطلق خطأً عند أي قيمة كانت البوابة سترفضها:
import OpenAI from 'openai';
import { azothGatewayHeaders } from '@azothos/sdk';
const openai = new OpenAI({
baseURL: 'https://www.azothos.ai/api/v1',
apiKey: process.env.AZOTH_API_KEY,
defaultHeaders: azothGatewayHeaders({ usecaseId }),
});
await openai.chat.completions.create(body, {
headers: azothGatewayHeaders({ decisionRef: creditFileId, subjectZone: 'FR' }),
});X-Azoth-UsecaseusecaseId: النظام (التفويض) الذي يخدمه الاستدعاءX-Azoth-Decision-RefdecisionRef: القرار التجاري، بمعرّف مبهمX-Azoth-Subject-ZonesubjectZone: مكان الأشخاص المعنيين — FR، US-CA، EU…X-Azoth-End-UserendUser: زائر نظام عام، بمعرّف مبهم، وليس عنوان بريد إلكتروني أبدًاX-Azoth-Challenge-PassedchallengePassed: رمز nonce لتحدٍّ اجتازه الزائرX-Azoth-Localeen أو fr أو es أو zh أو arX-Azoth-On-Behalf-Ofالإيصالات
تقرأ الدالة receiptOf(response | body | headers) إيصالًا، وdecodeReceipt(token) مطالباته، وتتحقق verifyReceipt(token, jwks) من توقيعه باستخدام WebCrypto. ومنذ SDK 1.2.0 ترفض أيضًا إيصالًا وُقّع عند لحظة الاختراق المعلَن لمفتاحه أو بعدها (حسب status وcompromised_at للمفتاح): تُنشر مفاتيح مساحة العمل وحالتها على /api/proof/keys/<workspaceId>.
حالات الرفض والإعفاءات
تقرأ الدالة parseRefusal(err) كتلة الرفض، وتعطي formatRefusal نصًا للعرض، وalternativeRequest(option) الترويسات والتغيير في الجسم لخيار ممتثل، وتطلب requestException(…) من مالك القاعدة إعفاءً محدود المدة. وعند تلقي 428، تعيد exhaustionChallengeOf(err) التحدي الواجب اجتيازه.
import { parseRefusal, formatRefusal, alternativeRequest, requestException } from '@azothos/sdk';
try {
await openai.chat.completions.create(body, { headers: { 'X-Azoth-Locale': 'fr' } });
} catch (err) {
const refusal = parseRefusal(err);
if (!refusal) throw err;
showToUser(formatRefusal(refusal));
const option = refusal.alternatives[0];
if (option) {
const { headers, body: change } = alternativeRequest(option);
await openai.chat.completions.create({ ...body, ...change }, { headers }); // governed again in full
} else if (refusal.exception.available) {
await requestException({
apiKey: process.env.AZOTH_API_KEY,
refusal,
justification: 'Quarter-end audit needs this model this week',
});
}
}وفي SDK أيضًا
createClientVault: احتفظ بمحتوى نظام في وضع الخزنة مشفّرًا بمفتاحك، في مخزنك؛ ولا يختم Azoth إلا البصمات.groundingSources(passages): المقاطع التي يجب أن تستند إليها الإجابة، للتحقق من الاستناد.runReferenceSet: شغّل مجموعة حالات مرجعية محفوظة في خزنتك وأرسل إيصالها، للتحكم في تغيير النماذج.
الإبلاغ عن الاستدعاءات التي تجري خارج البوابة
تغلّف الدوال wrapOpenAI وwrapAnthropic وwrapBedrock وwrapMistral وwrapGemini عميلك الحالي: يُبلَّغ Azoth بكل استدعاء — التكلفة، والزمن الكامن، والرموز — في الخلفية، مع امتدادات OpenTelemetry gen_ai.* اختيارية. وهذه الاستدعاءات مراقَبة لا خاضعة للحوكمة: لا يمكن لأي قاعدة إيقافها.
wrapOpenAI
import OpenAI from 'openai';
import { AzothClient, wrapOpenAI } from '@azothos/sdk';
const azoth = new AzothClient({ apiKey: process.env.AZOTH_API_KEY });
const openai = wrapOpenAI(new OpenAI(), azoth, {
provider: 'openai',
model: 'gpt-4o-mini',
agentId: 'support-bot', // the spend line it is attributed to
workflowId: 'ticket-triage',
});wrapAnthropic
import Anthropic from '@anthropic-ai/sdk';
import { AzothClient, wrapAnthropic } from '@azothos/sdk';
const azoth = new AzothClient({ apiKey: process.env.AZOTH_API_KEY });
const anthropic = wrapAnthropic(new Anthropic(), azoth);خيارات العميل
apiKeybaseUrlhttps://www.azothos.ai؛ ومضيفك الخاص في الاستضافة الذاتيةworkspaceIdclient.io.* وللمحاكاةenableTracing · tracertimeoutMsmaxRetriesRetry-After عند 429واجهة v1 REST API
تقبل معظم مسارات /api/v1 مفتاح API: Authorization: Bearer <key> أو X-Azoth-API-Key: <key>. ولا يصل المفتاح ذو النطاقات إلا إلى المسارات التي تقابلها نطاقاته. أما قراءات لوحة التحكم نفسها — /api/v1/me وقراءات GreenOps — فتتطلب جلسة مسجّلة بدلًا من ذلك، ولا تقبل مفتاحًا أبدًا. وكل مسار، وطريقة مصادقته، وحقوله، وإجاباته موجودة في مرجع واجهة API، المنشور أيضًا ملفًّا بصيغة OpenAPI.
POST /api/v1/chat/completionsPOST /api/v1/chatprovider صريح، وبدائل احتياطية، وتدفقPOST /api/v1/infer/resumeGET /api/v1/journalGET /api/v1/journal/export?format=dossierPOST /api/v1/decisions/exportPOST /api/v1/exceptionsPOST /api/v1/insights/{tool}insights:readPOST /api/v1/mcpGET /api/v1/usage · /api/v1/report · /api/v1/budgetsPOST /api/ingestGET /api/proof/keys/{workspaceId}POST /api/v1/chat
Authorization: Bearer <key>
{
"provider": "anthropic", // openai | anthropic | mistral | gemini | azure_openai
"model": "claude-haiku-4-5", // | openrouter | ollama | deepseek | huggingface | internal
"messages": [{ "role": "user", "content": "Summarise this document." }],
"maxTokens": 1024,
"stream": false,
"fallbackProviders": [{ "provider": "mistral", "model": "mistral-small-latest" }]
}الإجابات المتوقعة
400 validation_failedfield الحقل، ويقول error السبب.401402 budget_exceeded202 human_review_requiredapproval_request_id الخاص به.403policy_blocked، usecase_unresolved، usecase_not_approved، usecase_prohibited، usecase_archived، mandate_suspended، mandate_expired، kill_switch_active، jurisdiction_blocked، sovereignty_blocked، egress_blocked…428 exhaustion_challenge_required429exhaustion_slow أو exhaustion_blocked: الحقل retryAfterMs في الجسم، والترويسة Retry-After في الترويسات.503 governance_errorيُختم رفض الحوكمة ويحمل إيصاله. أما حالات رفض استنزاف التكاليف فتُحصى بدلًا من ذلك، وتُختم عند كل تغيير في المستوى. ويُشرح كل code في رموز الأخطاء، وهي الصفحة التي يقود إليها doc_url في الإجابة.