التوثيق
POST /v1/research
يحزِّم البحث وقراءة الصفحات في طلب واحد محسوب ويُرجِع حزمة أدلة: مصادر مرتّبة ومقتطفاتها وإشارات ثقة ودرجة من 0 إلى 1. اكتب إجابتك من sources[].excerpt وsignals — هذه مهمة الوكيل لا مهمتنا.
أنماط العمق والميزانيات الصارمة
- fast — بحث واحد k=8 بلا قراءة صفحات، يُرجِع المقتطفات فقط (excerpt=null). الميزانية 8 ثوانٍ.
- balanced — بحث واحد k=10 وقراءة أفضل 4 مصادر بالتوازي. الميزانية 20 ثانية.
- deep — بحث واحد k=16 وقراءة أفضل 6. الميزانية 40 ثانية.
- إعادة محاولة الجودة — في أي عمق: سؤال رسمي النية جولة أولاه بلا موثوق في المركز الأول يحصل على محاولة إضافية واحدة من الميزانية نفسها، تُقبل فقط لو أفضل (موثوق أول ← عدد موثوق أكبر). الرد: attempts:1|2.
تجاوز الميزانية ← HTTP 200 مع partial:true وpartialReason:"time_budget" — يُرجَع ما جُمع؛ ولا يُرسَل 504 بسبب الميزانية أبدًا.
معادلة الثقة
درجة جودة إشارات من 0 إلى 1 — حساب على الإشارات لا حكم نموذج.
confidence
base = 0.35*trustedTop1 + 0.25*min(trustedCount,3)/3
+ 0.20*(readOk/(readOk+readFailed)) + 0.20*min(distinctDomains,3)/3
coverage = best-effort → cap 0.55
read-failure ratio > 0.5 → −0.10
rounded to 2 decimals, clamped to [0,1]ما لا تفعله النسخة الأولى
- لا إجابة مكتوبة — الوكيل المستدعي يكتب من sources[].excerpt وsignals.
- لا نموذج ولا LLM — كل ما هنا استرجاع واستخلاص وحساب.
- لا استخلاص ادعاءات — المقتطفات نص صفحة خام.
- لا كشف تناقض — الإشارات أعداد لا أحكام.
يجمع البحث وقراءة الصفحات في طلب واحد محسوب. يُرجِع حزمة أدلة — مصادر مرتّبة بمقتطفاتها وإشارات ثقة ودرجة من 0 إلى 1 — ليكتب منها الوكيل المستدعي. طلب واحد = وحدة حصة واحدة؛ القراءات الداخلية لا تُحتسب.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
question | string (3..1000) | مطلوب | سؤال البحث (3–1000 حرف، بأي لغة). |
depth | 'fast' | 'balanced' | 'deep' | اختياري | fast: بحث واحد بلا قراءات (8 ثوانٍ) · balanced: بحث + أفضل 4 قراءات (20 ث) · deep: بحث + أفضل 6 قراءات (40 ث). استعلامات النية الرسمية تحصل على إعادة محاولة جودة واحدة من الميزانية نفسها في أي عمق — والرد يحمل attempts:1|2. الافتراضي balanced. |
lang | 'auto' | 'ar' | 'en' | اختياري | auto (افتراضي) أو ar أو en — تُمرَّر لموجِّه البحث. |
maxSources | integer (1..10) | اختياري | يتجاوز افتراضي العمق (fast 3، balanced 4، deep 6؛ الحد الأقصى 10). |
مثال
curl -X POST https://agw.orcanox.xyz/v1/research \ -H "Authorization: Bearer agw_…" \ -H "Content-Type: application/json" \ -d '{"question":"شروط تأشيرة زيارة عائلية للسعودية"}'
import requests r = requests.post("https://agw.orcanox.xyz/v1/research", headers={"Authorization": "Bearer agw_…"}, json={"question":"شروط تأشيرة زيارة عائلية للسعودية"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/v1/research", { method: "POST", headers: { "Authorization": "Bearer agw_…", "Content-Type": "application/json" }, body: JSON.stringify({"question":"شروط تأشيرة زيارة عائلية للسعودية"}) }); console.log(r.status, await r.json());
الاستجابة
json
{
"question": "شروط تأشيرة زيارة عائلية للسعودية",
"depth": "balanced",
"partial": false,
"coverage": "official",
"confidence": 0.87,
"signals": {
"trustedTop1": true,
"trustedCount": 3,
"distinctDomains": 5,
"readOk": 4,
"readFailed": 0,
"officialRetried": false
},
"sources": [
{
"rank": 1,
"url": "https://visa.mofa.gov.sa/…",
"title": "Family Visit Visa — MOFA",
"domain": "visa.mofa.gov.sa",
"trusted": true,
"snippet": "…",
"excerpt": "First ~1200 chars of clean page text…",
"method": "http",
"readOk": true,
"tookMs": 812
}
],
"routeAttempts": [
{
"route": "searxng",
"status": "ok",
"ms": 640
}
],
"tookMs": 5120,
"traceId": "rq_…"
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"question is required"} |
| 502 | fetch_failed | {"code":"fetch_failed","message":"all search routes failed"} |