ثلاثة استدعاءات، ولديك حكم

تفضِّل مرجعًا يقرؤه الحاسوب؟ ⁦openapi.yaml⁩ — كل حقل مُراجَع مقابل الخدمة العاملة، لا مكتوب من الذاكرة.

العنوان الأساسي ⁨https://api.kirelta.com⁩. وثِّق استدعاءات البيانات بالترويسة X-API-Key. واحصل على مفتاح من صفحة الحساب.

درِّب خط أساس

أرسِل دفعة صفوف تمثِّل سلوكًا سليمًا — بيانات من فترة كان النموذج يعمل فيها جيدًا. يتعلَّم ⁦Kirelta⁩ شكل تلك البيانات ويختار لها مراقبه بنفسه. وعلى كل صف أن يحمل العدد نفسه من الخصائص.

أرسِل outputs أيضًا. أضِف التنبؤات التي أنتجها نموذجك على تلك الصفوف نفسها، فيتعلَّم ⁦Kirelta⁩ السلوك الطبيعي لها كذلك — ليتمكَّن لاحقًا من التقاط نموذج انهار بينما البيانات الداخلة إليه ما زالت تبدو عادية تمامًا. وذلك عطل لا تراه أي أداة تراقب المدخلات وحدها.

POST /fit?model=NAME

curl -X POST "https://api.kirelta.com/fit?model=credit-risk" \
  -H "X-API-Key: kir_your_key" \
  -H "Content-Type: application/json" \
  -d '{"rows": [[0.8, 1.2, 0.4], [1.1, 0.9, 0.6]]}'

import requests

requests.post(
    "https://api.kirelta.com/fit",
    params={"model": "credit-risk"},
    headers={"X-API-Key": "kir_your_key"},
    json={"rows": healthy_rows},   # [[0.8, 1.2, 0.4], [1.1, 0.9, 0.6], ...300 healthy rows]
).json()

await fetch("https://api.kirelta.com/fit?model=credit-risk", {
  method: "POST",
  headers: {
    "X-API-Key": "kir_your_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ rows: healthyRows })
}).then(r => r.json());

المُخرَجات

{
  "status": "fitted",
  "model": "credit-risk",
  "n": 300,
  "features": 3,
  "baseline_fit": "clear"
}

قيِّم دفعة

الآن أرسِل صفوفًا حديثة — تلك التي تريد حكمًا عليها فعلًا. يقارنها ⁦Kirelta⁩ بخط الأساس ويجيب في كائن واحد.

POST /assess?model=NAME

curl -X POST "https://api.kirelta.com/assess?model=credit-risk" \
  -H "X-API-Key: kir_your_key" \
  -H "Content-Type: application/json" \
  -d '{"rows": [[0.9, 1.0, 0.5], [1.3, 0.8, 0.7]]}'

r = requests.post(
    "https://api.kirelta.com/assess",
    params={"model": "credit-risk"},
    headers={"X-API-Key": "kir_your_key"},
    json={"rows": recent_rows},   # [[0.9, 1.0, 0.5], [1.3, 0.8, 0.7], ...recent rows]
)
verdict = r.json()["verdict"]   # TRUSTED | DEGRADED | UNTRUSTED | INSUFFICIENT_EVIDENCE

const r = await fetch("https://api.kirelta.com/assess?model=credit-risk", {
  method: "POST",
  headers: {
    "X-API-Key": "kir_your_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ rows: recentRows })
});
const { verdict, action } = await r.json();

اقرأ الحكم

هذا هو المنتج كله. وكل ما تعرضه اللوحة مبنيٌّ من هذه الحقول — ولا يُحسب شيء آخر في أي مكان.

{
  "model": "t_e573d9984466::credit-risk",
  "verdict": "UNTRUSTED",
  "action": "BLOCK / escalate to a human",
  "flagged_rate": 1.0,
  "drift_alarmed": true,
  "n": 80,

  "martingale": 2203.05,
  "alarm_threshold": 20.0,
  "drift_started_at": 1,

  "feature_importance": [
    { "feature": 2, "importance": 0.3770 },
    { "feature": 1, "importance": 0.3561 },
    { "feature": 0, "importance": 0.2669 }
  ],
  "top_features": [2, 1, 0],

  "output_stability": {
    "active": true,
    "drift": true,
    "shifted": true,
    "n": 80
  },

  "notes": ["The data this model was trained on may itself contain anomalies..."],
  "note_codes": ["baseline_may_contain_anomalies"],

  "input_collapsed": false,
  "typicality_median": 0.4913,

  "temporal": { "elevated": false, "note": "..." }
}

اربطه بخدمتك

الشكل المعتاد: قيِّم الدفعة قبل أن تتصرَّف بناءً على التنبؤات، ثم تفرَّع على الحكم.

import requests

KIRELTA = "https://api.kirelta.com"
KEY     = "kir_your_key_here"

def can_i_trust(model, rows):
    r = requests.post(f"{KIRELTA}/assess?model={model}",
                      headers={"X-API-Key": KEY},
                      json={"rows": rows}, timeout=10)
    r.raise_for_status()
    return r.json()

verdict = can_i_trust("credit-risk", recent_feature_rows)

if verdict["verdict"] == "UNTRUSTED":
    escalate_to_human(verdict)          # don't act on the model's output
elif verdict["verdict"] in ("DEGRADED", "INSUFFICIENT_EVIDENCE"):
    # degraded, or no conclusion either way: act, but flag it
    log_for_review(verdict)
    serve(predictions)
else:
    serve(predictions)                  # TRUSTED

الشكل نفسه بلغة ⁦JavaScript⁩:

const KIRELTA = "https://api.kirelta.com";
const KEY = "kir_your_key_here";

async function canITrust(model, rows) {
  const r = await fetch(`${KIRELTA}/assess?model=${model}`, {
    method: "POST",
    headers: { "X-API-Key": KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ rows })
  });
  if (!r.ok) throw new Error(`assess failed: ${r.status}`);
  return r.json();
}

const verdict = await canITrust("credit-risk", recentFeatureRows);

if (verdict.verdict === "UNTRUSTED") {
  escalateToHuman(verdict);             // don't act on the model's output
} else if (["DEGRADED", "INSUFFICIENT_EVIDENCE"].includes(verdict.verdict)) {
  // degraded, or no conclusion either way: act, but flag it
  logForReview(verdict);
  serve(predictions);
} else {
  serve(predictions);                   // TRUSTED
}

كل ما تبقّى

بقية السطح، في مكان واحد.

GET /models

كل نموذج في مستأجرك، وكم خاصية يتوقَّع كلٌّ منها.

GET /model/meta?model=NAME

أي مراقب اختاره ⁦Kirelta⁩ لهذا النموذج ولماذا — مفيد حين تريد تسويغ حكم.

GET /usage

خطتك، والتنبؤات المستخدَمة هذا الشهر، ونماذجك مقابل حدِّك.

POST /keys · POST /keys/revoke

إنشاء مفاتيح الواجهة البرمجية وإبطالها. توثيق بالجلسة (Authorization: Bearer)، لا بالمفتاح — أو استخدم ببساطة صفحة الحساب.

GET /account/export · DELETE /account

نزِّل كل ما هو محفوظ عن حسابك، أو امحُه تمامًا.

GET /events · GET /alerts · POST /alerts

أحداث الثقة — ما الذي تغيَّر. يُرسل ⁦Kirelta⁩ حدثًا إلى خطَّافك حين يتغيَّر حكم نموذج، لا عند كل قراءة: فنموذج قُيِّم ألف مرة وهو معطَّل يرسل حدثًا واحدًا لا ألفًا. والتصعيد من متدهور إلى غير موثوق يمرُّ دائمًا، بفترة تهدئة أو بدونها — فسماع «متدهور» ثم صمت هو أخطر ما يمكن لهذا النظام أن يفعله بك. يُنبِّه ⁦Kirelta⁩؛ ولا يتصرَّف في أنظمتك أبدًا. لا يرى إلا ما ترسله إليه. لا يوجد مجدوِل. فإن توقَّفت خدمتك عن استدعاء /assess، صمَت ⁦Kirelta⁩، ولن يخبرك أي حدث بأنك عميت — فأبقِ ذلك الفحص في مراقبة زمن التشغيل لديك أنت. GET /alerts يخبرك هل القناة تعمل، لا ما هو مهيَّأ فقط. وإلى جانب الرابط و format يُعيد delivery — كم من تنبيهاتك الأخيرة قبلتها نقطة نهايتك فعلًا، ومتى كانت آخر محاولة، ولماذا فشلت إن فشلت. وإن كان consecutive_failures غير صفري، حملت الاستجابة أيضًا delivery_warningصريحًا. استطلعه، أو راقبه في اللوحة: فخطَّاف ويب توقَّف بصمت عن قبول التسليمات هو أداة مراقبة لم تعد تملكها.

GET /health

بلا توثيق. يُعيد {"status":"ok"} حين يكون المحرِّك يعمل.

حين يفشل شيء

لا يوجد النموذج إلا بعد /fit. فإن أجاب /assess بـ 409، فدرِّب خط الأساس أولًا.