Atlas Agent

Atlas resolves a free-text command into a structured, executable action your client runs against the map. Under the hood it is a tool-calling AI agent: it understands natural language in any language (first-class English and Arabic, including Jordanian dialect), picks the right action, and — for factual questions — grounds its answer in live Navvo data (real places, ratings, and current traffic) rather than guessing. One endpoint covers search, navigation, pins, layer/style control, day-plan itineraries, fleet optimization, and grounded conversational answers.

The response contract is unchanged and backward-compatible — you still switch on action exactly as before. Replies come back in the same language the user wrote in. Atlas is resilient: if the primary model is briefly unavailable it automatically falls back to a local model and a deterministic parser, so the endpoint keeps working.

Scope required: places.

Authentication: Atlas requires an identified caller — either a signed-in Navvo user (Bearer token, as on navvo.io) or your API key (x-api-key). Anonymous requests receive 401.

POST /ai/atlas

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" }'

Every response has a reply (a short human sentence, in the user's language), an action, a model (always navvo-ai), and unavailable. The other fields depend on the action:

Planning examples

// "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." }

Duration is parsed from the text (3 hours, 90 minutes, half-day → 240, afternoon → 240); interests are matched against a category vocabulary (cafe, restaurant, museum, park, shopping, historic, art, market, nature, …).

Other examples

{ "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"

Grounded answers

For factual questions Atlas fetches real Navvo data before replying — it never invents places, ratings, coordinates, or traffic:

// "is there a pharmacy near me?"  → answered from live place search
{ "action": "answer", "reply": "Yes — the closest is Airport Bridge Pharmacy (4.8), with Airport Pharmacy nearby too." }

// "كيف حالة السير الآن؟"  (how is traffic now?) → answered from live traffic, in Arabic
{ "action": "answer", "reply": "لا توجد تقارير مرور حية في منطقتك الآن. أخبرني باسم الشارع وسأتحقق لك." }