دليل استخدام LAMH

كل ما تحتاجه لربط LAMH بمساعدك الذكي في نحو 15 دقيقة: ماذا ترسل، وأين تضعه، وماذا تفعل بالنتيجة.

المحتويات

  1. ماذا يفعل LAMH؟
  2. قبل أن تبدأ
  3. البدء السريع في 3 خطوات
  4. مثال بلغة Python
  5. مثال بلغة JavaScript
  6. مثال من سطر الأوامر (curl)
  7. ماذا يعيد LAMH؟
  8. حقول الشهادة
  9. الأحكام: ماذا تفعل بكل مقطع؟
  10. إبقاء LAMH محدّثًا
  11. إذا تعذّر الوصول إلى LAMH
  12. مرجع الواجهة
  13. الباقات والحدود
  14. الأخطاء
  15. الأمان والخصوصية
  16. أسئلة شائعة

ماذا يفعل LAMH؟

مساعدك الذكي يبحث في مستنداتك، ثم يرسل المقاطع التي وجدها (نسمّيها chunks) إلى نموذج لغوي ليجيب منها. فإذا كان المقطع قديمًا، أو عُدّل، أو حُذف، أو يستند إلى نظام أو معيار لم يعد ساريًا، فسيجيب النموذج بثقة رغم ذلك. يقف LAMH بين البحث والنموذج، ويفحص كل مقطع قبل أن يصل إلى النموذج.

البحث يجد المقاطع → LAMH يصدر شهادة لكل مقطع → النموذج يجيب من السياق المعتمد

قبل أن تبدأ

إذا فقدت مفتاحك، فراسل [email protected] من البريد الذي سجّلت به، وسنصدر لك مفتاحًا جديدًا ونلغي القديم.

البدء السريع في 3 خطوات

  1. زامن مستنداتك
    أرسل كل مستند مرة واحدة على شكل قائمة مقاطع مرتبة، واستخدم المقاطع نفسها الموجودة في فهرس البحث عندك. doc_id اسم ثابت تختاره أنت للمستند (حروف إنجليزية وأرقام و. _ : / -). سيعيد LAMH رقم version، أي إصدار المستند. وكلما تغيّر المستند فأرسله كاملًا مرة أخرى، فيسجّل LAMH الإصدار الجديد.
  2. احفظ ثلاث علامات مع كل مقطع
    في فهرس البحث (قاعدة المتجهات أو محرك البحث)، احفظ بجانب نص كل مقطع: doc_id، وchunk_no وهو ترتيب المقطع في المستند بدءًا من 0، وversion. بهذه العلامات يتعرّف LAMH على المقطع لاحقًا.
  3. اطلب الشهادة قبل كل سؤال للنموذج
    بعد أن يعيد البحث المقاطع، أرسلها إلى POST /v1/certify مع علاماتها ونصها. ثم ضع حقل context الذي يعيده LAMH في الطلب الموجّه للنموذج بدل المقاطع الخام. يحتوي هذا الحقل على النص الحالي مع تنبيه واضح لكل معلومة قديمة، ويستبعد المقاطع المحجوبة.

مثال بلغة Python

import os
from lamh_client import Lamh          # download: https://lamh.mubtkrat.ai/sdk/lamh_client.py

lamh = Lamh(os.environ["LAMH_API_KEY"])          # keep the key in an environment variable

# 1) Sync: once now, and again every time a document changes
r = lamh.sync([
    {"doc_id": "refund-policy", "chunks": [
        "Refunds are accepted within 30 days of purchase.",
        "VAT in Saudi Arabia is 15% and is included in the price.",
    ]},
])
version = r["versions"]["refund-policy"]   # save this number with each chunk in your search index

# 2) Certify: before every model call, send the chunks your search returned
retrieved = [
    {"doc_id": "refund-policy", "chunk_no": 0, "version": version,
     "text": "Refunds are accepted within 30 days of purchase."},
]
out = lamh.certify(retrieved, lang="en")      # lang="ar" for Arabic notes

# 3) Use: give the model out["context"] instead of the raw chunks
prompt = (
    "Answer only from these sources. Respect any notice marked with a warning sign.\n\n"
    + out["context"] + "\n\nQuestion: " + question
)

مثال بلغة JavaScript

// Node 18+ or any server runtime with fetch. Never call LAMH from a browser: the key must stay secret.
const LAMH = "https://api.mubtkrat.ai";

async function lamh(method, path, body) {
  const r = await fetch(LAMH + path, {
    method,
    headers: { Authorization: `Bearer ${process.env.LAMH_API_KEY}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  const j = await r.json();
  if (!r.ok) throw new Error(`${r.status} ${j.error.code}: ${j.error.message}`);
  return j;
}

// 1) Sync
const s = await lamh("PUT", "/v1/documents", {
  documents: [{ doc_id: "refund-policy", chunks: ["Refunds are accepted within 30 days of purchase."] }],
});
// 2) Certify
const out = await lamh("POST", "/v1/certify", {
  lang: "en",
  chunks: [{ doc_id: "refund-policy", chunk_no: 0, version: s.versions["refund-policy"],
             text: "Refunds are accepted within 30 days of purchase." }],
});
// 3) Use out.context in your prompt

مثال من سطر الأوامر (curl)

export LAMH_API_KEY="lamh_live_..."

# Sync a document
curl -X PUT https://api.mubtkrat.ai/v1/documents \
  -H "Authorization: Bearer $LAMH_API_KEY" -H "Content-Type: application/json" \
  -d '{"documents":[{"doc_id":"refund-policy","chunks":["Refunds are accepted within 30 days of purchase."]}]}'

# Certify retrieved chunks
curl -X POST https://api.mubtkrat.ai/v1/certify \
  -H "Authorization: Bearer $LAMH_API_KEY" -H "Content-Type: application/json" \
  -d '{"lang":"en","chunks":[{"doc_id":"refund-policy","chunk_no":0,"version":1,"text":"Refunds are accepted within 30 days of purchase."}]}'

# Check your plan and usage
curl https://api.mubtkrat.ai/v1/usage -H "Authorization: Bearer $LAMH_API_KEY"

ماذا يعيد LAMH؟

بعد المزامنة

{"epoch": 3, "root": "0abb2816…2740", "versions": {"refund-policy": 2}, "stored_chunks": 2}

بعد طلب الشهادة

هذا رد فعلي. المقطع الأول عُدّل (صارت مدة الاسترداد 30 يومًا بدل 14)، فاستبدله LAMH بالنص الحالي. والمقطع الثاني يستند إلى ضريبة قيمة مضافة 5% في السعودية، وقد صارت 15% منذ 2020، فأضاف LAMH تنبيهًا.

{
  "certificates": [
    {
      "ref": {"doc_id": "refund-policy", "chunk_no": 0, "version": 1},
      "intact": true, "current": false, "change": "material",
      "verdict": "REPLACED",
      "notes": ["This passage was outdated and has been replaced with the current version since 2026-10-27."],
      "text": "Refunds are accepted within 30 days of purchase.",
      "basis": []
    },
    {
      "ref": {"doc_id": "refund-policy", "chunk_no": 1, "version": 2},
      "intact": true, "current": true, "change": "same",
      "verdict": "VALID_WITH_NOTICE",
      "basis": [{"authority": "sa.vat_rate5.1439", "status": "superseded", "effective_to": "2020-07-01",
                 "current_reference": "VAT 15% (from 1 July 2020)", "evidence": "https://zatca.gov.sa/…"}],
      "notes": ["Note: this passage relies on VAT 5%, which is superseded since 2020-07-01; current reference: VAT 15%."],
      "text": "VAT in Saudi Arabia is 5% and is included in the price."
    }
  ],
  "context": "[1] (refund-policy) ⚠ This passage was outdated and has been replaced …\nRefunds are accepted within 30 days of purchase.\n\n[2] (refund-policy) ⚠ Note: …",
  "epoch": 3
}

حقول الشهادة

refالمقطع الذي أرسلته: doc_id وchunk_no وversion.
intacttrue إذا كان النص مطابقًا للإصدار الذي زامنته (فحص تشفيري).
currenttrue إذا كان أحدث إصدار من هذا المقطع.
changeنوع التغيير: same (لا تغيير) · cosmetic (شكلي) · minor (طفيف) · material (جوهري) · removed (محذوف) · tampered (عُبث به)
basisالأنظمة والمعايير والإرشادات وإصدارات البرامج التي يستند إليها المقطع، مع حالتها وتاريخ انتهائها وبديلها الحالي ومصدرها الرسمي.
verdictالحكم، أي ماذا تفعل بالمقطع (انظر الجدول التالي).
notesتنبيهات مقروءة باللغة التي طلبتها.
textالنص الذي تعطيه للنموذج (وهو النص الحالي إذا استُبدل المقطع).

الأحكام: ماذا تفعل بكل مقطع؟

الحكممعناهماذا تفعل
VALIDسليم وحديث، ولا شيء يستدعي التنبيه.استخدمه.
VALID_WITH_NOTICEحديث، لكنه يستند إلى نظام أو معيار أُلغي أو استُبدل.استخدمه مع التنبيه، وهو موجود أصلًا في context.
REFRESHEDتغيّر تغيّرًا بسيطًا بعد فهرسته، فاستبدل LAMH النص الحالي به دون تنبيه.استخدم text.
REPLACEDتغيّر جوهري، فاستُبدل بالنص الحالي مع تنبيه.استخدم text والتنبيه.
BLOCKEDعُبث به، أو أن مصدره لم يعد موجودًا.لا ترسله إلى النموذج. حقل context يستبعده تلقائيًا.

تريد المقاطع الصالحة فقط؟

usable = lamh.usable(retrieved, lang="en")    # drops BLOCKED chunks, keeps current text
chunks_for_model = [c["text"] for c in usable]

إبقاء LAMH محدّثًا

إذا تعذّر الوصول إلى LAMH

تنتظر المكتبة حتى 10 ثوانٍ. قرّر مسبقًا ماذا يفعل مساعدك في هذه الحالة:

from lamh_client import Lamh, LamhError
try:
    out = lamh.certify(retrieved, lang="en")
    context = out["context"]
except (LamhError, OSError):
    # LAMH unreachable or quota reached: choose your policy.
    # Regulated answers (legal, medical, finance): refuse and ask the user to retry.
    # General assistants: answer, but log the question for review.
    context = None

مرجع الواجهة

الطريقةالمسارالغرض
PUT/v1/documentsمزامنة المستندات: {documents:[{doc_id, chunks:[…]}], delete:[doc_id]}
POST/v1/certifyإصدار الشهادات: {chunks:[{doc_id, chunk_no, version, text}], lang:"ar"|"en"}
GET/v1/documents/<doc_id>إصدار المستند الحالي وعدد مقاطعه (لا يعيد النص أبدًا)
GET/v1/usageباقتك وحدودها واستهلاكك هذا الشهر
GET/v1/registry?sector=المرجعيات التي يتابعها LAMH وحالتها
GET/v1/rootالجذر الموقّع والمفتاح العام، لتتحقق من LAMH بنفسك
GET/v1/accountبيانات حسابك
GET/v1/healthحالة الخدمة (لا يحتاج مفتاحًا)

كل طلب ما عدا /v1/health يحتاج الترويسة Authorization: Bearer <مفتاحك>.

الباقات والحدود

الباقةمقاطع معتمدة شهريًامقاطع مخزّنةطلبات في الثانية
التجربة (14 يومًا)10,00020,0005
Starter50,00025,00010
Pro1,000,000500,00050
المؤسسات50,000,00020,000,000500

اعرف أرقامك أنت في أي وقت عبر GET /v1/usage.

الأخطاء

تعود الأخطاء بهذا الشكل: {"error": {"code": "…", "message": "…"}}.

HTTPالرمزماذا تفعل
400bad_chunk / bad_chunks / bad_doc_id / bad_jsonصحّح محتوى الطلب: كل مقطع يحتاج doc_id وchunk_no وversion وtext.
401unauthorizedالمفتاح مفقود، أو فيه خطأ، أو أُلغي.
402certify_quota / storage_quotaبلغت حد الشهر. رقِّ باقتك أو انتظر الشهر التالي.
402subscription_expiredجدّد اشتراكك من الموقع.
413too_largeقسّم الطلب (الحد 4 ميجابايت).
429rate_limited / write_rate_limitedطلبات كثيرة. انتظر ثوانيَ ثم أعد المحاولة.
503integrity_failureراسل [email protected].

الأمان والخصوصية

أسئلة شائعة

هل يحل LAMH محل قاعدة المتجهات أو النموذج؟

لا. أبقِ البحث والنموذج كما هما، فـLAMH مجرد استدعاء واحد بينهما.

مع أي نموذج أو إطار عمل يعمل؟

مع أيٍّ منها: OpenAI وClaude وGemini وLlama وLangChain وLlamaIndex، أو كودك الخاص. LAMH يحتاج فقط نص المقطع وعلاماته الثلاث.

هل يجب أن أرسل كل مستنداتي؟

فقط المستندات التي يبحث فيها مساعدك، لأن LAMH يقارن المقاطع المسترجعة بها.

ما اللغات المدعومة؟

المقاطع بأي لغة. والتنبيهات بالعربية أو الإنجليزية حسب حقل lang.

ما سرعته؟

عادةً بضعة أجزاء من الألف من الثانية لكل مقطع، وهذا أقل بكثير من الوقت الذي يستغرقه النموذج ليجيب.

تحتاج مساعدة في الربط؟ راسل [email protected] مع بريد حسابك ونص رسالة الخطأ. لا ترسل مفتاح API أبدًا.