مرجع الواجهة البرمجية

وكيل أطلس (تحكّم لغوي)

حوِّل الأوامر بالّلغة الطبيعية إلى إجراءات خريطة مُهيكلة — بحث، اتجاهات، دبابيس، تحكّم بالطبقات، والآن خطط رحلات يومية وتحسين مسارات الأساطيل.

وكيل أطلس

يحوّل أطلس أمراً نصّياً حراً إلى إجراء خريطة مُهيكَل وقابل للتنفيذ يشغّله تطبيقك على الخريطة. وهو في جوهره وكيل ذكاء اصطناعي يستدعي الأدوات: يفهم اللغة الطبيعية بأي لغة (وفي مقدّمتها العربية والإنجليزية، بما في ذلك اللهجة الأردنية)، يختار الإجراء الصحيح، ولأي سؤال معلوماتي يبني إجابته على بيانات Navvo الحيّة (أماكن وتقييمات حقيقية وحالة سير آنية) بدل التخمين. نقطة واحدة تغطّي البحث والملاحة والدبابيس والتحكّم بالطبقات/الأنماط وخطط الرحلات اليومية وتحسين الأساطيل والإجابات الحوارية المبنيّة على بيانات.

عقد الاستجابة لم يتغيّر ومتوافق مع الإصدارات السابقة — لا تزال تتفرّع حسب action كما كان. وتعود الردود بنفس لغة المستخدم. أطلس مرن: إذا تعذّر الوصول للنموذج الأساسي مؤقتاً يتحوّل تلقائياً إلى نموذج محلي ومحلِّل حتمي، فتبقى النقطة تعمل.

النطاق المطلوب: places.

المصادقة: يتطلب Atlas مُستدعيًا معرَّفًا — إمّا مستخدم Navvo مسجّل الدخول (رمز Bearer كما في navvo.io) أو مفتاح API الخاص بك (x-api-key). الطلبات المجهولة تتلقى 401.

أطلس محايد تجاه النموذج: كل استجابة تُرجِع "model": "navvo-ai". المحرّك الأساسي تفصيل داخلي في Navvo وقد يتغيّر دون إشعار — لا تعتمد أبداً على اسم نموذج بعينه.

POST /ai/atlas

الحقل	النوع	ملاحظات
`message`	string	مطلوب — أمر المستخدم باللغة الطبيعية
`userName`	string	اختياري — اسم المستخدم المسجّل؛ يخاطبه Atlas باسمه الأول
`context`	string	اختياري — تلميح سياق/محادثة قصير

curl -s -X POST "https://navvo.io/api/v1/ai/atlas" \
  -H "x-api-key: $NAVVO_API_KEY" -H "content-type: application/json" \
  -d '{ "message": "plan a 3 hour trip with cafes and museums" }'

لكل استجابة reply (جملة بشرية قصيرة) وaction وmodel وunavailable. وتعتمد بقية الحقول على الإجراء:

`action`	حقول إضافية	المعنى — ما الذي يفعله تطبيقك
`search`	`query`	نفّذ بحث أماكن عن `query` واعرض النتائج
`directions`	`query`	ابدأ التوجيه إلى `query`
`navigate`	`query`	بدء الإرشاد خطوة بخطوة إلى `query` فورًا ("ابدأ الملاحة إلى…")
`pin`	`query`	ضع دبّوساً عند `query`
`locate`	`query`	وسِّط/قرِّب الخريطة على `query`
`control`	`target`, `value`	بدِّل طبقة/نمط/لوحة — `target` مثل `traffic`/`satellite`/`3d`/`transit`/`weather`؛ و`value` هو `on`/`off`/`toggle`
`itinerary`	`timeBudgetMin`, `interests`	ابنِ خطة يوم — نادِ `POST /itinerary/auto` بهذه + موقع المستخدم
`optimize_fleet`	—	حسِّن محطات توصيل المستخدم — نادِ محسِّن الأسطول
`report_incident`	`query` (النوع: `accident`/`hazard`/`police`/`camera`/`closure`/`jam`)	تبليغ حادث بدون استخدام اليدين — سجِّله عند موقع المستخدم عبر `POST /incidents` ("في حادث قدام")
`answer`	—	مفتوح — `reply` ردّ حواري

أمثلة التخطيط

// "plan a 3 hour trip with cafes and museums"
{ "action": "itinerary", "timeBudgetMin": 180, "interests": ["cafe","museum"],
  "reply": "Planning a 3-hour itinerary around cafe, museum near you." }

// "what can I do in 90 minutes near here"
{ "action": "itinerary", "timeBudgetMin": 90, "interests": [], "reply": "Planning a 1.5-hour itinerary near you." }

// "optimize my deliveries"
{ "action": "optimize_fleet", "reply": "Optimizing your stops into the fastest route order." }

تُستخرَج المدّة من النص (3 hours، 90 minutes، half-day ← 240، afternoon ← 240)؛ وتُطابَق الاهتمامات مع مفردات تصنيف (cafe، restaurant، museum، park، shopping، historic، art، market، nature، …).

أمثلة أخرى

{ "action": "directions", "query": "the airport", "reply": "Routing you to the airport." }   // "directions to the airport"
{ "action": "search", "query": "cafes", "reply": "Here's what I found for \"cafes\"." }        // "find cafes nearby"
{ "action": "control", "target": "traffic", "value": "on", "reply": "Turning on traffic." }    // "turn on traffic"

إجابات مبنيّة على بيانات

للأسئلة المعلوماتية يجلب أطلس بيانات Navvo الحقيقية قبل أن يجيب — لا يخترع أماكن أو تقييمات أو إحداثيات أو حالة سير:

// "is there a pharmacy near me?"  → إجابة من بحث الأماكن الحيّ
{ "action": "answer", "reply": "Yes — the closest is Airport Bridge Pharmacy (4.8), with Airport Pharmacy nearby too." }

// "كيف حالة السير الآن؟"  → إجابة من السير الحيّ، بالعربية
{ "action": "answer", "reply": "لا توجد تقارير مرور حية في منطقتك الآن. أخبرني باسم الشارع وسأتحقق لك." }

حين يكون الطلب إجراءً على الخريطة (بحث، اتجاهات، ملاحة، تحديد موقع، دبّوس، تحكّم بالطبقات، خطة يوم، أسطول) يُرجِع أطلس ذلك الإجراء بحقوله — وينفّذه تطبيقك تماماً كما هو موثّق أعلاه. ولا تعود action: "answer" إلا للرسائل المفتوحة أو المعلوماتية. وبما أنّ المخطط لم يتغيّر، لا تحتاج التكاملات الحالية أي تعديل.

المهام (بيانات الحشود)

تحسين بيانات تشاركي مُحفَّز — إظهار مهام صغيرة لسدّ فجوات البيانات القريبة، وجمع الإجابات في قائمة المراجعة، ومنح المساهمين نقاطاً.

المستخدمون والمزامنة

الحسابات والملفات الشخصية والأماكن المحفوظة والسجل ومشاركة الموقع الحي — واجهة البيانات الشخصية لبناء تطبيق مستهلك بتسجيل دخول على Navvo.