التوثيق

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‏ — كل ما هنا استرجاع واستخلاص وحساب.
  • لا استخلاص ادعاءات — المقتطفات نص صفحة خام.
  • لا كشف تناقض — الإشارات أعداد لا أحكام.
POST /v1/research api-key · search #

يجمع البحث وقراءة الصفحات في طلب واحد محسوب. يُرجِع حزمة أدلة — مصادر مرتّبة بمقتطفاتها وإشارات ثقة ودرجة من 0 إلى 1 — ليكتب منها الوكيل المستدعي. طلب واحد = وحدة حصة واحدة؛ القراءات الداخلية لا تُحتسب.

الطلب

الحقلالنوعالوصف
questionstring (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‏ — تُمرَّر لموجِّه البحث.
maxSourcesinteger (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":"شروط تأشيرة زيارة عائلية للسعودية"}'

الاستجابة

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مثال
400bad_request{"code":"bad_request","message":"question is required"}
502fetch_failed{"code":"fetch_failed","message":"all search routes failed"}