API_DOCS.md

Smart Travel AI Agent API Documentation

This document describes how a web application or frontend client can connect to and interact with the Smart Travel AI Agent hosted on Hugging Face Spaces.

🔗 Connection Information

• Base URL: https://youmei295-planning-agent.hf.space
• CORS: Enabled for all origins (*), so it can be called directly from frontend web applications (e.g., Next.js, React, Vue, Vanilla JS).
• Communication Protocol: HTTPS / REST API

---

🟢 1. Health Check Endpoint

Used to verify if the AI agent backend is up and running.

Endpoint: GET /health or GET /

Response Example (200 OK):

{
  "status": "ok",
  "message": "Smart Travel AI API is running"
}

---

🚀 2. Trip Planning & Chat Endpoint

This is the main endpoint used to communicate with the agent. The system automatically routes the message to either a normal conversation (chat) or complex trip planning based on the user's intent.

Endpoint: POST /api/plan
Headers:

• Content-Type: application/json

📥 Input Format (Request Payload)

Send a JSON body with the following structure:

{
  "message": "Mình muốn đi chơi cuối tuần ở Bình Thạnh, ưu tiên quán cafe yên tĩnh và ăn đồ nướng.",
  "start_date": "2024-12-01",  // (Optional) Expected start date, Format: YYYY-MM-DD
  "num_days": 1,               // (Optional) Number of days for the trip (Max: 3)
  "session_id": "user-123"     // (Optional) For tracking user sessions
}

Field Details:

• message (string, required): The user's prompt, question, or requirement.
• start_date (string, optional): Explicit start date chosen from the frontend UI.
• num_days (integer, optional): Explicit number of days chosen from the frontend UI. If omitted, the AI will try to infer the duration from the message.
• session_id (string, optional): An ID to keep track of the user's conversation thread (if applicable).

---

📤 Output Formats (Response)

The API returns different structures depending on how the AI categorizes the user's input.

Scenario A: Chat / Small Talk / Asking for more info

If the user just says "Hello" or provides insufficient information for a trip, the agent responds conversationally.

Response Example (200 OK):

{
  "status": "chat",
  "total_cost": "0 VNĐ",
  "itinerary_markdown": "Xin chào! Bạn muốn lên kế hoạch đi chơi ở đâu? Hãy cho mình biết thêm thông tin nhé.",
  "timeline": []
}

Scenario B: Successful Trip Plan Generation

If the user provides a valid travel request, the system processes it, queries the database, and returns a detailed itinerary and timeline.

Response Example (200 OK):

{
  "status": "success",
  "total_cost": "500.000 - 1.000.000 VNĐ",
  "itinerary_markdown": "## 🌟 Kế hoạch đi Bình Thạnh của bạn\n\n**Buổi sáng:** Cafe Yên...\n...",
  "timeline": [
    {
      "time": "08:00 - 10:00",
      "activity": "Uống cafe",
      "location": "Quán Cafe Yên",
      "location_id": "uuid-from-supabase",
      "cost_estimate": "50000"
    },
    {
      "time": "18:00 - 20:00",
      "activity": "Ăn đồ nướng",
      "location": "Panda BBQ",
      "location_id": "uuid-from-supabase",
      "cost_estimate": "250000"
    }
  ]
}

Scenario C: Error Handling

If an internal error occurs during processing.

Response Example (500 Internal Server Error):

{
  "detail": "Lỗi kết nối cơ sở dữ liệu..."
}

---

💻 Example Connection Method (JavaScript/Fetch)

Here is a simple example of how a web app can connect to this API using the standard fetch API:

async function requestTripPlan(userMessage) {
  const url = "https://youmei295-planning-agent.hf.space/api/plan";
  
  const payload = {
    message: userMessage,
    start_date: "2024-12-01", // Or retrieve from your UI date picker
    num_days: 1               // Or retrieve from your UI dropdown
  };

  try {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();

    if (data.status === "success") {
      console.log("Trip Planned Successfully!");
      console.log("Total Cost:", data.total_cost);
      console.log("Markdown Report:", data.itinerary_markdown);
      console.log("Timeline Array:", data.timeline);
      
      // TODO: Render the markdown and timeline array in your UI
    } else if (data.status === "chat") {
      console.log("Agent Message:", data.itinerary_markdown);
      
      // TODO: Show this message in a chat bubble
    }

  } catch (error) {
    console.error("Error communicating with AI Agent:", error);
  }
}

// Example usage:
// requestTripPlan("Mình muốn đi Quận 1 uống cafe và đi dạo.");