LAMH Guide
Everything you need to connect LAMH to your AI assistant in about 15 minutes: what to send, where to put it, and what to do with the answer.
Contents
- What LAMH does
- Before you start
- Quick start: 3 steps
- Python example
- JavaScript example
- Command-line example (curl)
- What LAMH returns
- Certificate fields
- Verdicts: what to do
- Keeping LAMH up to date
- If LAMH cannot be reached
- API reference
- Plans and limits
- Errors
- Security and privacy
- Frequently asked questions
What LAMH does
Your AI assistant searches your documents and sends the passages it finds (called chunks) to a language model. If a passage is outdated, edited, deleted, or relies on a law or standard that is no longer in force, the model still answers confidently. LAMH sits between your search and your model and checks every chunk first.
Before you start
- Your API key: it starts with
lamh_live_and is shown once when you sign up or pay. Store it in an environment variable such asLAMH_API_KEY. - API address:
https://api.mubtkrat.ai - Where to call it: from your server or backend only. Never put the key in a web page or mobile app.
- Language: Python 3.8+ (our SDK has no dependencies), JavaScript, or any language that can send HTTPS requests.
Quick start: 3 steps
- Sync your documents
Send each document once as a list of chunks, in order. Use the same chunks your search index already uses.doc_idis your own stable name for the document (letters, numbers,. _ : / -). LAMH replies with the document'sversion. Send the whole document again whenever it changes; LAMH records the new version. - Save three labels with every chunk
In your search index (vector database or search engine), storedoc_id,chunk_no(the chunk's position, starting at 0) andversionnext to each chunk's text. These labels are how LAMH recognises the chunk later. - Certify before every model call
After your search returns chunks, send them toPOST /v1/certifywith their labels and text. Put the returnedcontextin your prompt instead of the raw chunks. It contains the current text and a clear notice for anything outdated, and it leaves out blocked chunks.
Python example
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 example
// 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
Command-line example (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"
What LAMH returns
After sync
{"epoch": 3, "root": "0abb2816…2740", "versions": {"refund-policy": 2}, "stored_chunks": 2}
After certify
A real response: the first chunk had been edited (14 days became 30 days), so LAMH replaced it with the current text. The second relies on Saudi VAT at 5%, which changed to 15% in 2020, so LAMH added a notice.
{
"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
}
Certificate fields
ref | The chunk you sent: doc_id, chunk_no, version. |
intact | true if the text matches the version you synced (cryptographic check). |
current | true if it is the latest version of that chunk. |
change | same · cosmetic · minor · material · removed · tampered |
basis | Laws, standards, guidelines or software versions the chunk relies on, with their status, end date, current replacement and official source. |
verdict | What to do with the chunk (see below). |
notes | Human-readable notices, in the language you asked for. |
text | The text to give the model (current text when it was replaced). |
Verdicts: what to do
| Verdict | Meaning | Your action |
|---|---|---|
VALID | Intact and current, nothing to flag. | Use it. |
VALID_WITH_NOTICE | Current, but relies on an authority that was repealed or superseded. | Use it with the notice (already in context). |
REFRESHED | A small change since you indexed it; LAMH silently swapped in the current text. | Use text. |
REPLACED | A material change; replaced with the current text plus a notice. | Use text and the notice. |
BLOCKED | Tampered with, or the source no longer exists. | Do not send it to the model. context already leaves it out. |
Only want the usable chunks?
usable = lamh.usable(retrieved, lang="en") # drops BLOCKED chunks, keeps current text
chunks_for_model = [c["text"] for c in usable]
Keeping LAMH up to date
- When a document changes, send the whole document again with the same
doc_id. Update theversionlabel in your search index when you re-index. - Until you re-index, LAMH still protects you: old chunks come back as REFRESHED or REPLACED with the current text.
- To delete documents:
{"documents": [], "delete": ["old-faq"]}. Their chunks will then be BLOCKED. - Up to 1,000 documents per sync request, 500 chunks per certify request, 4 MB per request.
If LAMH cannot be reached
The SDK waits up to 10 seconds. Decide in advance what your assistant should do:
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
API reference
| Method | Path | Purpose |
|---|---|---|
PUT | /v1/documents | Sync documents: {documents:[{doc_id, chunks:[…]}], delete:[doc_id]} |
POST | /v1/certify | Certify chunks: {chunks:[{doc_id, chunk_no, version, text}], lang:"en"|"ar"} |
GET | /v1/documents/<doc_id> | A document's current version and chunk count (never its text) |
GET | /v1/usage | Your plan, limits and this month's usage |
GET | /v1/registry?sector= | The authorities LAMH tracks and their status |
GET | /v1/root | Signed ledger root and public key, so you can verify LAMH independently |
GET | /v1/account | Your account details |
GET | /v1/health | Service status (no key needed) |
Every request except /v1/health needs the header Authorization: Bearer <your key>.
Plans and limits
| Plan | Certified chunks / month | Stored chunks | Requests / second |
|---|---|---|---|
| Trial (14 days) | 10,000 | 20,000 | 5 |
| Starter | 50,000 | 25,000 | 10 |
| Pro | 1,000,000 | 500,000 | 50 |
| Enterprise | 50,000,000 | 20,000,000 | 500 |
Check your own numbers at any time with GET /v1/usage.
Errors
Errors come back as {"error": {"code": "…", "message": "…"}}.
| HTTP | code | What to do |
|---|---|---|
| 400 | bad_chunk / bad_chunks / bad_doc_id / bad_json | Fix the request body: every chunk needs doc_id, chunk_no, version and text. |
| 401 | unauthorized | Key missing, mistyped or revoked. |
| 402 | certify_quota / storage_quota | Monthly limit reached. Upgrade your plan or wait for next month. |
| 402 | subscription_expired | Renew on the website. |
| 413 | too_large | Split the request (max 4 MB). |
| 429 | rate_limited / write_rate_limited | Too many requests. Wait a few seconds and retry. |
| 503 | integrity_failure | Contact [email protected]. |
Security and privacy
- Your chunks are stored encrypted with a key unique to your account; API keys are never stored, only a fingerprint of them.
- Any change to your stored data outside LAMH is detected and stops service for your account until it is checked.
- You can verify the signed ledger yourself with
GET /v1/root. - Data is hosted in the EU (Frankfurt). See the Data Processing Agreement and Privacy Policy.
Frequently asked questions
Does LAMH replace my vector database or my model?
No. Keep your search and your model. LAMH is one call between them.
Which model or framework does it work with?
Any: OpenAI, Claude, Gemini, Llama, LangChain, LlamaIndex, or your own code. LAMH only needs the chunk text and its three labels.
Do I have to send all my documents?
Only the documents your assistant searches. LAMH compares retrieved chunks against them.
Which languages?
Chunks can be in any language. Notices are in Arabic or English (lang).
How fast is it?
Typically a few milliseconds per chunk, well below the time a model takes to answer.