"Docs: Add Architecture, Agents & Troubleshooting guides; Update README (Demo links coming soon)"

README.md

@@ -8,7 +8,7 @@ sdk_version: 5.49.1
 app_file: app.py
 pinned: false
 license: mit
-short_description: Your journey, in perfect rhythm
+short_description: Don't just plan the trip. Design the flow.
 tags:
   - mcp-in-action-track-enterprise
   - mcp-in-action-track-consumer
@@ -17,10 +17,16 @@ tags:
 
 # ✨ LifeFlow AI: Intelligent Trip Planning System
 
-> **Your journey, in perfect rhythm.** > An enterprise-grade, multi-agent system that orchestrates your daily schedule using real-world data, hybrid AI architecture, and mathematical optimization.
+[![Gradio](https://img.shields.io/badge/UI-Gradio%205.49.1-orange?style=flat-square&logo=gradio)](https://gradio.app/)
+[![Agno](https://img.shields.io/badge/Orchestration-Agno-blueviolet?style=flat-square)](https://github.com/agno-agi/agno)
+[![Python](https://img.shields.io/badge/Python-3.11-blue?style=flat-square&logo=python)](https://www.python.org/)
+[![Docker](https://img.shields.io/badge/Docker-Enabled-2496ED?style=flat-square&logo=docker)](https://www.docker.com/)
+[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
 
----
+> **Your journey, in perfect rhythm.**
+> An enterprise-grade, multi-agent system that orchestrates your daily schedule using real-world data, hybrid AI architecture, and mathematical optimization.
 
+---
 ## 👥 Team
 
 ### Team Information:
@@ -29,9 +35,9 @@ tags:
 
 
 ## 📺 Demo & Submission
-- Demo Video: [Coming Soon]
-- Social Media Post: [Coming Soon]
-- Submission Date: November 2025
+- **Demo Video:** [Coming Soon]
+- **Social Media Post:** [Coming Soon]
+- **Submission Date:** November 2025
 
 
 ## 📖 Overview
@@ -91,25 +97,82 @@ LifeFlow AI allows deep customization via the **Settings** panel:
 * **Groq:** Llama 3.3 70B, GPT-OSS 120B, Kimi K2.
 
 ### Fast Mode (Hybrid)
-Enable **Fast Mode** in settings to offload search and routing tasks to Groq. This significantly reduces latency and API costs while maintaining high-quality reasoning for the final output.
+Enable **Fast Mode** in settings to offload search and routing tasks to Groq. 
+This significantly reduces latency and API costs while maintaining high-quality reasoning for the final output.
 
 ---
 
-## 📦 Tech Stack
+## 🛠️ Tech Stack & Components
 
-* **Framework:** [Agno](https://github.com/agno-agi/agno) (formerly Phidata) for Agent Orchestration.
-* **UI/UX:** Gradio 5.x with custom CSS themes. (update to Gradio 6.x soon)
-* **Services:** Google Maps Platform (Places, Routes), OpenWeatherMap.
-* **Infrastructure:** Python 3.11, Docker.
+| Component | Technology                                                    | Description |
+| :--- |:--------------------------------------------------------------| :--- |
+| **Frontend** | [Gradio](https://www.gradio.app/)                             | Reactive UI with custom CSS, Stepper, and Map integration. |
+| **Orchestration** | [Agno](https://github.com/agno-agi/agno)                      | Manages Agent state, memory, and team coordination. |
+| **Tool Protocol** | [FastMCP](https://github.com/jlowin/fastmcp)                  | Exposes Python functions as standardized AI tools. |
+| **Models** | [Google Gemini](https://ai.google.dev/)                       | **Flash** for Leader/Planner (Reasoning), **Flash-Lite** for Workers (Speed). |
+| **Optimization** | [Google OR-Tools](https://developers.google.com/optimization) | Solves TSPTW (Traveling Salesperson Problem with Time Windows). |
+| **Data Layer** | [SQLite](https://www.sqlite.org/index.html)                   | Local file-based repository for high-speed context offloading. |
 
 ---
 
 ## 💻 Local Installation
 
-To run LifeFlow AI locally:
+To run LifeFlow AI locally, follow these steps:
+
+### Prerequisites
+- Python 3.11+
+- Virtualenv (recommended)
+
+### Installation Steps
+
+1. **Clone the repository**
+```bash
+   git clone [https://huggingface.co/spaces/Marco310/LifeFlow-AI](https://huggingface.co/spaces/Marco310/LifeFlow-AI)
+   cd LifeFlow-AI
+```
+   
+2. Create and activate a virtual environment
+```bash
+# Linux/MacOS
+python -m venv venv
+source venv/bin/activate
+
+# Windows
+python -m venv venv
+venv\Scripts\activate
+```
 
+3. Install dependencies
 ```bash
-TODO
+pip install -r requirements.txt
 ```
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+4. Set up Environment Variables Create a .env file in the root directory (optional if using UI for keys):
+```env
+# Search API
+GOOGLE_MAPS_API_KEY=your_key_here
+OPENWEATHER_API_KEY=your_key_here
+
+# MODEL API
+GOOGLE_API_KEY=your_key_here
+OPENAI_API_KEY=your_key_here
+GROQ_API_KEY=your_key_here
+```
+
+5. Run the application
+```bash
+python app.py
+```
+
+## 📚 Documentation
+
+Explore the technical details behind LifeFlow AI:
+
+- [**🏗️ Architecture Design**](doc/ARCHITECTURE.md)
+  > Deep dive into the **"Dual-Brain" system**, **Context Offloading**, and **Exclusive MCP Channels**.
+  
+- [**🤖 The Agent Team**](doc/AGENTS.md)
+  > Detailed roster of our 6 specialized agents, their models, tools, and prompt strategies.
+
+- [**🔧 Troubleshooting Guide**](doc/TROUBLESHOOTING.md)
+  > Solutions for common API errors (Google/OpenWeather), JSON parsing issues, and Docker setup.

doc/AGENTS.md

@@ -0,0 +1,83 @@
+# 🤖 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.
+```

doc/ARCHITECTURE.md

@@ -0,0 +1,132 @@
+# 🏗️ System Architecture
+
+LifeFlow AI implements a novel **"Dual-Brain"** architecture combined with a **Context-Offloading Protocol** to solve the scalability issues of traditional Agentic workflows. This document details the system design, data flow, and infrastructure.
+
+## 📐 High-Level Design
+
+The system is built on a modular microservices-like architecture using **Agno (Phidata)** for orchestration and **FastMCP** for tool isolation.
+
+```mermaid
+graph TD
+    User[User Interface] -->|Gradio Websocket| App[Application Core]
+    App -->|Input Analysis| Planner[📋 Planner Agent]
+    
+    subgraph "Core Team (State Machine)"
+        Leader[👨‍✈️ Team Leader]
+        Leader -->|Delegates| Scout[🗺️ Scout]
+        Leader -->|Delegates| Optimizer[⚡ Optimizer]
+        Leader -->|Delegates| Navigator[🧭 Navigator]
+        Leader -->|Delegates| Weatherman[🌤️ Weatherman]
+        Leader -->|Delegates| Presenter[📊 Presenter]
+    end
+
+    Planner -->|Task List JSON| Leader
+    
+    subgraph "The 'Hot Potato' Data Pipeline"
+        direction LR
+        DB[(POI Repository / SQLite)]
+        Scout -.->|Write Raw POIs| DB
+        DB -.->|Read Ref ID| Optimizer
+        Optimizer -.->|Write Ordered List| DB
+        DB -.->|Read Opt ID| Navigator
+        Navigator -.->|Write Routes| DB
+        DB -.->|Read Nav ID| Weatherman
+        Weatherman -.->|Write Final Timeline| DB
+    end
+```
+
+## 🚀 Key Architectural Patterns
+1. Context Offloading Protocol ("Hot Potato")
+Traditional agents pass massive JSON blobs (search results, reviews, coordinates) back and forth in the chat context, quickly hitting token limits and causing hallucinations.
+
+
+### LifeFlow's Solution:
+- Data Isolation: Agents NEVER see the full data payload.
+- Reference Passing: Agents only exchange Reference IDs (e.g., scout_result_123).
+- Mechanism:
+  1. Scout finds 50+ locations, saves them to poi_repo, and returns {"scout_ref": "uuid"} to the Leader.
+  2. Leader passes this UUID to the Optimizer.
+  3. Optimizer loads data from the repo, solves the TSPTW problem, and saves the result.
+  * Result: Reduces token consumption by ~90% for complex trips.
+
+2. Exclusive MCP Channels (Tool Isolation)
+In standard multi-agent setups, all tools are often dumped into a shared context, confusing the LLM (e.g., the "Optimizer" trying to use "Weather" tools).
+
+### LifeFlow's Solution (in app.py):
+We implement a custom Lifecycle Manager that spins up isolated FastMCP connections for each agent.
+- Scout Agent $\leftrightarrow$ Channel A (Only search_and_offload)
+- Optimizer Agent $\leftrightarrow$ Channel B (Only optimize_from_ref)
+- Navigator Agent $\leftrightarrow$ Channel C (Only calculate_traffic_and_timing)
+This guarantees 100% Tool Usage Accuracy and prevents agents from hallucinating tool calls.
+
+### 🔗 The Unifying Link: Shared State via Reference IDs
+
+While the **Execution Channels** (A, B, C) are strictly isolated to prevent tool hallucinations, they share a **Unified State Layer**.
+
+The "Glue" connecting these isolated environments is the **Database Reference ID** (e.g., `scout_ref_uuid`).
+
+* **Mechanism:**
+    * **Channel A (Scout)** executes a search, writes the heavy JSON payload to the shared **POI Repository (DB)**, and returns *only* the ID `ref_123`.
+    * The **Leader Agent** passes `ref_123` to **Channel B (Optimizer)**.
+    * **Channel B** uses its tool (`optimize_from_ref`) to "hydrate" the data by reading `ref_123` from the same shared DB, processes it, and saves a new `ref_456`.
+
+This architecture ensures that while **Tools are Private** (security & accuracy), **Data is Global** (accessibility).
+
+```mermaid
+graph LR
+    subgraph Execution ["⚡ Isolated Execution Channels"]
+        A[Channel A: Scout]
+        B[Channel B: Optimizer]
+        C[Channel C: Navigator]
+    end
+
+    subgraph Storage ["💾 Unified Storage Layer"]
+        DB[(POI Repository)]
+    end
+
+    %% Data Flow
+    A -->|Write Data| DB
+    B <-->|Read/Write Data| DB
+    C <-->|Read/Write Data| DB
+
+    %% ID Passing
+    A -.->|Pass Ref ID| B
+    B -.->|Pass Ref ID| C
+    
+    %% Styling
+    style DB fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+## 🛠️ Tech Stack & Compon**ents**
+
+| Component | Technology        | Description |
+| :--- |:------------------| :--- |
+| **Frontend** | Gradio 5.49.1     | Reactive UI with custom CSS, Stepper, and Map integration. |
+| **Orchestration** | Agno (Phidata)    | Manages Agent state, memory, and team coordination. |
+| **Tool Protocol** | FastMCP           | Exposes Python functions as standardized AI tools. |
+| **Models** | Google Gemini 2.5 | **Flash** for Leader/Planner (Reasoning), **Flash-Lite** for Workers (Speed). |
+| **Optimization** | Google OR-Tools   | Solves TSPTW (Traveling Salesperson Problem with Time Windows). |
+| **Data Layer** | SQLite / JSON     | Local file-based repository for high-speed context offloading. |
+
+
+## 🔄 Data Flow Example
+1. User Input: "Plan a day in SF, visit Pier 39 and get crab."
+
+2. Planner: Converts to structured JSON Tasks.
+
+3. Leader: Receives Tasks → Delegates to Scout.
+    > Scout: Calls Google Places API → Saves 20 candidates → Returns ref_scout.
+
+4. Leader: Delegates to Optimizer.
+    > Optimizer: Loads ref_scout → Runs OR-Tools → Returns ref_opt (Sorted).
+
+5. Leader: Delegates to Navigator.
+    > Navigator: Loads ref_opt → Calls Google Routes (Traffic) → Returns ref_nav.
+
+6. Leader: Delegates to Weatherman.
+    > Weatherman: Loads ref_nav → Checks OpenWeather → Returns ref_final.
+
+7. Leader: Delegates to Presenter.
+    > Presenter: Reads ref_final → Generates UI Report.
+
+8. User sees a complete, optimized itinerary with maps and weather.

doc/TROUBLESHOOTING.md

@@ -0,0 +1,58 @@
+# 🔧 Troubleshooting Guide
+
+This guide addresses common issues when running LifeFlow AI locally, particularly regarding API integrations and Docker environments.
+
+## 🔴 Common Errors & Solutions
+
+### 1. JSON Parsing Errors (Scout Agent)
+**Symptom:** `❌ Error: Invalid JSON format.`
+**Cause:** The LLM (especially smaller models like Flash-Lite) may output markdown backticks or Python-style booleans (`True` instead of `true`) in the JSON.
+**Solution:**
+* LifeFlow includes a `_robust_parse_json` method in `scout_toolkit.py` that attempts to auto-repair malformed JSON.
+* If this persists, verify that your prompt explicitly requests "Raw JSON, no markdown".
+
+### 2. Google Maps API: `REQUEST_DENIED` or `OVER_QUERY_LIMIT`
+**Symptom:** Agent loop fails, or Map is empty.
+**Check:**
+* Ensure the following APIs are enabled in your Google Cloud Console:
+    * **Places API (New)**
+    * **Routes API**
+    * **Maps JavaScript API** (for UI)
+* **Billing:** You must have a billing account linked, even for the free tier.
+
+### 3. MCP Connection Failed / Port Conflicts
+**Symptom:** `❌ [System] MCP Connection Failed` in the console log.
+**Cause:** The application attempts to spawn multiple subprocesses for `mcp_server_lifeflow.py`. If a previous run didn't close properly, ports/files might be locked.
+**Solution:**
+* Manually kill python processes: `pkill -f mcp_server_lifeflow.py`
+* Restart the application.
+
+### 4. "Ref ID Not Found" Loop
+**Symptom:** The Leader Agent keeps asking the Scout to search again because it "cannot find the data".
+**Cause:** The `poi_repo` (SQLite/File) might be persisting data from an old session, or the `session_id` mismatch.
+**Solution:**
+* Delete the `tmp/` directory or the database file to clear the cache.
+* The system includes an auto-correction mechanism (visible in `weather_toolkit.py`) that tries to fetch the *latest* ID if the specific one is missing. Check the logs for `🔄 Auto-Correcting`.
+
+## ⚙️ Environment Variables (`.env`)
+
+Make sure your `.env` file matches this structure exactly:
+
+```ini
+# Core LLM
+GOOGLE_API_KEY=AIzaSy...
+
+# Tools
+GOOGLE_MAPS_API_KEY=AIzaSy...  # Must have Places & Routes enabled
+OPENWEATHER_API_KEY=abc123...
+
+# Optional (for Fast Mode)
+GROQ_API_KEY=gsk_...
+```
+
+## 🐛 Debugging Mode
+To see the raw "Hot Potato" data flow:
+1. Open core_team.py.
+   - Set debug_mode=True in creat_team.
+2. Open config.py
+   - Set LOG_LEVEL="DEBUG".