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):**
```json
{
  "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:

```json
{
  "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):**
```json
{
  "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):**
```json
{
  "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):**
```json
{
  "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:

```javascript
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.");
```