ابدأ مجانًا →

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-Usecase
usecaseId: النظام (التفويض) الذي يخدمه الاستدعاء
X-Azoth-Decision-Ref
decisionRef: القرار التجاري، بمعرّف مبهم
X-Azoth-Subject-Zone
subjectZone: مكان الأشخاص المعنيين — FR، US-CA، EU…
X-Azoth-End-User
endUser: زائر نظام عام، بمعرّف مبهم، وليس عنوان بريد إلكتروني أبدًا
X-Azoth-Challenge-Passed
challengePassed: رمز nonce لتحدٍّ اجتازه الزائر
X-Azoth-Locale
لغة الرفض: en أو fr أو es أو zh أو ar
X-Azoth-On-Behalf-Of
الشخص الذي يُجرى الاستدعاء من أجله — معرّفه في SCIM أو بريده — بمفتاح خدمة مسموح له بتسمية الأشخاص؛ تضبطه بنفسك (الإسناد البشري)

الإيصالات

تقرأ الدالة 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);

خيارات العميل

apiKey
إلزامي: مفتاح API لمساحة العمل
baseUrl
افتراضيًا https://www.azothos.ai؛ ومضيفك الخاص في الاستضافة الذاتية
workspaceId
إلزامي لـ client.io.* وللمحاكاة
enableTracing · tracer
إصدار امتدادات OpenTelemetry
timeoutMs
لكل محاولة، 30 000 افتراضيًا
maxRetries
إجمالي المحاولات عند 429 أو 5xx، 3 افتراضيًا؛ وتُحترم الترويسة Retry-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/completions
البوابة الخاضعة للحوكمة، متوافقة مع OpenAI
POST /api/v1/chat
البوابة الخاضعة للحوكمة مع provider صريح، وبدائل احتياطية، وتدفق
POST /api/v1/infer/resume
تنفيذ استدعاء محتجز بعد الموافقة عليه
GET /api/v1/journal
القرارات المختومة
GET /api/v1/journal/export?format=dossier
ملف التدقيق، بصيغة ZIP
POST /api/v1/decisions/export
ملف قرار، حسب مرجع القرار
POST /api/v1/exceptions
طلب إعفاء من رفض
POST /api/v1/insights/{tool}
أدوات القراءة الخاصة بالمساعد، بالنطاق insights:read
POST /api/v1/mcp
بوابة MCP الخاضعة للحوكمة، بمفتاح مرتبط بوكيل
GET /api/v1/usage · /api/v1/report · /api/v1/budgets
الاستخدام، وتقرير النفقات، والميزانيات
POST /api/ingest
الإبلاغ عن الاستدعاءات التي تجري خارج البوابة
GET /api/proof/keys/{workspaceId}
المفاتيح العامة لمساحة العمل (JWKS)، دون مفتاح
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_failed
لم يجتز جسم الطلب التحقق من الصحة: يسمّي field الحقل، ويقول error السبب.
401
مفتاح API مفقود أو غير صالح أو ملغى.
402 budget_exceeded
رفضت ميزانيةٌ الاستدعاء قبل النموذج.
202 human_review_required
محتجز بانتظار شخص؛ استأنفه بـ approval_request_id الخاص به.
403
رفضته قاعدة: policy_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_required
يطلب نظام عام من الزائر اجتياز تحدٍّ.
429
حدّ للمعدل، أو exhaustion_slow أو exhaustion_blocked: الحقل retryAfterMs في الجسم، والترويسة Retry-After في الترويسات.
503 governance_error
تعذّر تشغيل الحوكمة والنشر مغلق عند الفشل: أعد المحاولة.

يُختم رفض الحوكمة ويحمل إيصاله. أما حالات رفض استنزاف التكاليف فتُحصى بدلًا من ذلك، وتُختم عند كل تغيير في المستوى. ويُشرح كل code في رموز الأخطاء، وهي الصفحة التي يقود إليها doc_url في الإجابة.