التوثيق

البداية

أنشئ حساباً وخذ مفتاحك من لوحتك. أرسل المفتاح مع كل طلب في الترويسة:

Authorization: Bearer hk_live_...

يظهر المفتاح مرة واحدة عند إنشائه، فاحفظه في مكان آمن ولا تضعه في كود يعمل في المتصفح.

طلب قرار

POST https://158.101.254.194.sslip.io/v1/systemone متوافق مع عقد Jev. ترسل الحالة والأسئلة:

state: نص، أو كائن JSON، أو قائمة نصوص.
questions: كائن، المفتاح فيه اسم تختاره للسؤال. لكل سؤال نوع:
- choice اختيار واحد من criteria (مفتاح ووصف، حتى 255 خياراً).
- noul نعم أو لا، ويرجع احتمال «نعم». وcriteria اختيارية: {"true": …, "false": …}.
- score درجة على سلّم من 2 إلى 10 مستويات مرتبة من الأقل للأعلى.
policy (اختياري): قواعدك نصاً. النموذج يلتزم بها قبل حدسه.

{
  "state": "وصلني الطرد مكسور وأبي فلوسي ترجع اليوم",
  "questions": {
    "team":  {"type": "choice", "instructions": "أي فريق يتولى الطلب؟",
              "criteria": {"refunds": "الاسترجاع", "parcels": "الطرود التالفة", "login": "الدخول"}},
    "angry": {"type": "noul",  "instructions": "العميل غاضب"},
    "level": {"type": "score", "instructions": "مستوى الانزعاج",
              "criteria": ["هادئ", "منزعج", "غاضب جداً"]}
  },
  "policy": "الطرد التالف يذهب لفريق الطرود"
}

فهم الجواب

{
  "model": "hasm-cloud/haiku",
  "answers": {
    "team":  {"type": "choice", "choice": "parcels", "confidence": 0.85, "grade": "decided",
              "probabilities": {"refunds": 0.08, "parcels": 0.9, "login": 0.02}, "expected_accuracy": 0.97},
    "angry": {"type": "noul", "noul": 0.93, "grade": "decided"},
    "level": {"type": "score", "score": 1.9, "level": 2, "confidence": 0.84, "grade": "likely",
              "legend": {"0": "هادئ", "1": "منزعج", "2": "غاضب جداً"}}
  },
  "usage": {"input_tokens": 612, "output_tokens": 88, "quota_left": 998},
  "elapsedMs": 1412,
  "hasm": {"request_id": "…", "memory": null, "examples_used": 3,
           "calibration": {"team": {"threshold": 0.72, "learned": true, "verdicts": 140, "accuracy": 0.96}}}
}

كل جواب يحمل درجة تقول لكودك ماذا يفعل به:

decided حاسم: احتمال الجواب فوق عتبة السؤال ولا شيء يستدعي إنساناً. نفّذه آلياً.
likely مرجّح: هذا الأقرب، لكن أكّده قبل التنفيذ.
review راجعه: حسم غير متأكد. يرجع أفضل مرشح كتلميح فقط مع "abstained": true، والقرار لشخص.

confidence تُحسب من شكل توزيع الاحتمالات بنفس معادلات Jev، وexpected_accuracy هي الدقة التي قستها أنت فعلاً على أجوبة بنفس الاحتمال. وhasm.escalation ينبهك إذا كان الموضوع حساساً، مثل المال.

الثبات والذاكرة

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

المعايرة الذاتية

لا تحتاج أن تختار عتبات. لكل سؤال، حسم يقارن الاحتمال الذي أعطاه بنتيجة كل تأكيد وتصحيح، ثم يختار أدنى عتبة حققت عندها الأجوبة الدقة المطلوبة في حسابك (95% افتراضياً، وتغيّرها من الإعدادات).

تبدأ كل الأسئلة بعتبة افتراضية، وتُستبدل بالعتبة المتعلَّمة بعد 30 حكماً على الأقل.
الدقة تُحكم بحدها الأدنى المحتمل وليس بنسبتها الخام، فلا تفتح بضعة أحكام محظوظة التنفيذ الآلي.
إذا صار النموذج مفرط الثقة في سؤال ما، ترتفع عتبته تلقائياً. وإذا أثبت دقته، تنخفض.
GET /v1/accuracy يعرض الدقة المقاسة والعتبة الحالية لكل سؤال.

نصائح للدقة

اجعل مفاتيح الخيارات كلمات واضحة مثل refunds، وليس أرقاماً.
كل سؤال يحكم على شيء واحد. القرار المركب ابنه في كودك من عدة أسئلة.
اكتب وصف كل خيار كما تشرحه لموظف جديد.
أكّد الأجوبة الصحيحة وصحّح الخاطئة. الاثنان يقيسان الدقة، والتصحيح وحده لا يكفي.

مجموعات الأسئلة

بدل إرسال الأسئلة مع كل طلب، احفظها مرة واحدة باسم، ثم أرسل الاسم فقط في "contract": "support_v1". المعايرة والتعلّم يعملان لكل مجموعة على حدة.

PUT    /v1/contracts/support_v1   {"description": "...", "policy": "...", "questions": {...}}
GET    /v1/contracts
DELETE /v1/contracts/support_v1
GET    /v1/templates
POST   /v1/contracts/from-template/triage

التأكيد والتصحيح

POST /v1/confirm    {"request_id": "..."}
POST /v1/feedback   {"request_id": "...", "question": "team", "human_answer": "refunds"}
GET  /v1/accuracy

كل 20 حكماً جديداً على مجموعة محفوظة، يتدرب نموذج صغير لكل سؤال تلقائياً ويُختبر على حالات لم يرها، ولا يُفعّل إلا إذا كانت نتائجه جيدة. بعدها يحسم الحالات المتكررة بنفسه، أسرع وأرخص.

الأدوات الجاهزة

كل أداة في صفحة الأدوات تعمل من الـ API أيضاً: ترسل الحقول وقائمة حتى 100 عنصر، وترجع لكل عنصر حكماً واضحاً مع أجوبة الأسئلة.

GET  https://158.101.254.194.sslip.io/v1/tools
POST https://158.101.254.194.sslip.io/v1/tools/scam-check
{"fields": {}, "items": ["تم إيقاف بطاقتك، حدّث بياناتك من الرابط"]}

كل نتيجة فيها verdict وtone (ok أو warn أو bad أو info) وsure وrequest_id، فتؤكدها أو تصححها بنفس طريقة أي قرار.

أمثلة كود

Python

import httpx

r = httpx.post("https://158.101.254.194.sslip.io/v1/systemone",
    headers={"Authorization": "Bearer hk_live_..."},
    json={"state": "...", "contract": "support_v1"}).json()

team = r["answers"]["team"]
if team["grade"] == "decided":
    route(team["choice"])
else:
    queue_for_review(r["hasm"]["request_id"])

JavaScript

const r = await fetch("https://158.101.254.194.sslip.io/v1/systemone", {
  method: "POST",
  headers: { "Authorization": "Bearer hk_live_...", "content-type": "application/json" },
  body: JSON.stringify({ state: "...", contract: "support_v1" })
}).then(res => res.json());

curl

curl https://158.101.254.194.sslip.io/v1/systemone \
  -H "Authorization: Bearer hk_live_..." \
  -H "content-type: application/json" \
  -d '{
    "state": "وصلني الطرد مكسور وأبي فلوسي ترجع اليوم",
    "questions": {
      "team":  {"type": "choice", "instructions": "أي فريق يتولى الطلب؟",
                "criteria": {"refunds": "الاسترجاع", "parcels": "الطرود التالفة", "login": "الدخول"}},
      "angry": {"type": "noul", "instructions": "العميل غاضب"}
    }
  }'

الحدود

حتى 255 خياراً للسؤال، ومن 2 إلى 10 مستويات للدرجة، وحتى 64 سؤالاً في الطلب حسب خطتك.
حجم الطلب حتى 512KB، و1,200 طلب في الدقيقة لكل مفتاح، وسقف زمني 5 ثوانٍ للقرار.
"classification": "confidential" تعني: لا يُرسل النص لأي نموذج خارجي. للبيانات السرية استخدم النسخة التي تعمل داخل شركتك.