doc/AGENTS.md

# 🤖 The Agent Team

LifeFlow AI is not a single bot, but a coordinated **Multi-Agent System (MAS)**. Each agent is a specialized "worker" with restricted permissions, specific tools, and a distinct model configuration to optimize for cost and performance.

## 👥 The Roster

### 1. 📋 Planner (The Architect)
* **Model:** `Gemini 2.5 Flash` (High Reasoning)
* **Role:** The entry point. It never executes tasks but "understands" them.
* **Responsibility:**
    * Parses vague natural language into structured JSON.
    * Assigns categories (MEAL, SIGHTSEEING) and priorities.
    * Estimates durations based on context (e.g., "coffee" = 30m, "museum" = 2h).

### 2. 👨‍✈️ Team Leader (The Orchestrator)
* **Model:** `Gemini 2.5 Flash`
* **Role:** The State Machine. It manages the `core_team`.
* **Responsibility:**
    * Receives the Task List from the Planner.
    * Enforces the strict pipeline sequence: `Scout -> Optimizer -> Navigator`.
    * Handles error recovery (e.g., if Scout fails, it asks to retry).
    * **Crucial:** It does *not* see the raw data, only the **Reference IDs**.

### 3. 🗺️ Scout (The Explorer)
* **Model:** `Gemini 2.5 Flash-Lite` (Speed Optimized)
* **Tools:** `ScoutToolkit` (Google Places API)
* **Key Feature:** **Robust JSON Parsing**. The Scout includes a custom parser to handle malformed JSON often output by LLMs, ensuring high reliability even with smaller models.
* **Task:** Performs "Adaptive Search" (allocating more API budget to harder queries).

### 4. ⚡ Optimizer (The Mathematician)
* **Model:** `Gemini 2.5 Flash-Lite`
* **Tools:** `OptimizationToolkit` (Google OR-Tools)
* **Algorithm:** TSPTW (Traveling Salesperson Problem with Time Windows).
* **Logic:**
    * Loads POIs from the DB.
    * Calculates a Distance Matrix (Manhattan/Haversine approximation).
    * Reorders stops to minimize travel time while respecting opening hours.
    * Marks tasks as "Dropped" if they don't fit the schedule.

### 5. 🧭 Navigator (The Driver)
* **Model:** `Gemini 2.5 Flash-Lite`
* **Tools:** `NavigationToolkit` (Google Routes API)
* **Task:**
    * Takes the logical sequence from the Optimizer.
    * Queries **Google Routes API** for precise "Traffic-Aware" travel times.
    * Generates the polyline geometry for the map UI.

### 6. 🌤️ Weatherman (The Meteorologist)
* **Model:** `Gemini 2.5 Flash-Lite`
* **Tools:** `WeatherToolkit` (OpenWeatherMap)
* **Innovation:** **Dynamic Timezone Handling**.
    * Calculates the exact arrival time at each stop.
    * Fetches the specific forecast for that *hour* and *location*.
    * Retrieves Air Quality Index (AQI).

---

## 🧠 Model Configuration Strategy

We use a tiered model strategy to balance intelligence and latency:

| Agent Tier | Model | Rationale |
| :--- | :--- | :--- |
| **Brain Tier**<br>(Planner, Leader) | `gemini-2.5-flash` | Requires complex instruction following and context management. Needs higher context window. |
| **Muscle Tier**<br>(Scout, Optimizer, etc.) | `gemini-2.5-flash-lite` | Performs single-shot tool execution. Speed is prioritized over nuance. |

## 🛡️ Tool Isolation (Exclusive Mode)

In `app.py`, we implement a unique **Exclusive MCP Connection**:

```python
# Pseudo-code logic from app.py
AGENT_TOOL_MAP = {
    "scout": "search_and_offload",
    "optimizer": "optimize_from_ref",
    # ...
}

# Each agent gets its own private server instance
for agent, tool in AGENT_TOOL_MAP.items():
    connect_mcp(agent, include_tools=[tool])
This prevents the "Navigator" from accidentally trying to search for places, or the "Scout" from trying to calculate routes, significantly reducing loop errors.
```